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PREFACE 



This manual describes the external features of the CRAY-1 Operating 
System (COS). The manual consists of three parts: 



PART 1 SYSTEM DESCRIPTION 

This part describes the system components, storage of 
information on the CRAY-1, and job processing. An 
introduction to job control language is also included. 



PART 2 JOB CONTROL LANGUAGE 

In this part, the format of each COS control statement is 
given, along with an explanation of the function of each. 



PART 3 MACRO INSTRUCTIONS 

In part 3, CAL language macro instructions are described 
and in some cases examples are provided. 



Other CRI publications that may be of interest to the reader are: 

• CRAY-1 Hardware Reference Manual, publication 2240004 

• CRAY-1 S Series Hardware Reference Manual, publication HR-0808 

• CRAY-1 FORTRAN (CFT) Reference Manual, publication SR-0009 
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INTRODUCTION 



The CRAY-1 Operating System (COS) is a multiprogramming operating system 
for CRAY-l Computer Systems. The operating system provides for 
efficient use of system resources by monitoring and controlling the flow 
of work presented to the system in the form of jobs. The operating 
system optimizes resource usage and resolves conflicts when more than one 
job is in need of resources. 

COS is a collection of programs residing in CRAY-l CPU memory or on 
system mass storage following startup of the system. (Startup is the 
process of bringing the CRAY-l and the operating system to an operational 
state.) 

Jobs are presented to the CRAY-l by one or more computers referred to as 
front-end computers (also referred to as stations in Cray manuals) . 
A front-end computer may be any of a variety of computer systems. Since 
a front-end computer system operates asynchronously under control of its 
own operating system, software execution on the front-end computer system 
is beyond the scope of this publication. 

COS includes linkages providing for the initiation and control of 
interactive jobs and data transfers between the CRAY-l and front-end 
terminals. These features are available only where supported by the 
front-end system. 

The FORTRAN compiler (CFT) , library routines, the CAL assembler, and the 
UPDATE source maintenance program are described in separate publications. 



HARDWARE REQUIREMENTS 

The CRAY-l Operating System executes on the basic configuration of the 
I CRAY-l Computer System. A CRAY-l models A, B, S/500 or S/1000 consists 
of a Central Processing Unit (CPU) , a minicomputer-based Maintenance 
Control Unit (MCU) , and a mass storage subsystem. 



I 



A CRAY-l Model S/1200 through S/4400 consists of a CPU, an I/O Subsystem 
with a mass storage subsystem and an optional IBM-compatible tape 
subsystem. 
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COS operates with any of four central memory size options: one-half 
million, one million, two million, and four million words. 

The mass storage for Models S/500 through S/1000 is a mass storage 
subsystem consisting of two or more disk storage units. The mass storage 
for Models S/1200 through S/4400 is conventionally composed of disk 
storage units on the I/O Subsystem but can optionally include a mass 
storage subsystem. 

The I/O Subsystem consists of from two to four I/O processors and 
one-half, one, four, or eight million words of shared Buffer Memory. The 
optional tape subsystem is composed of at least one block multiplexer 
channel, one tape controller, and two tape units. The tape units 
supported are IBM-compatible 9-track, 200 ips, 1600/6250 bpi devices. 

Figure 1-1 illustrates a basic system configuration. For more information 
about CRAY-1 hardware characteristics, refer to the CRAY-l Hardware 
Reference Manual, Models A and B, publication HR-0004 and to the CRAY-1 S 
Series Hardware Reference Manual, publication HR-0808. 



SYSTEM INITIALIZATION 

COS is loaded into memory {deadstarted) and activated through a system 
startup procedure performed at the MCU or I/O Subsystem. At startup, 
permanent datasets are re-established on mass storage. (Permanent 
datasets survive deadstart; the user can always assume that they are 
present. See part 1, section 2 of this manual for more information on 
datasets.) 



CENTRAL MEMORY ASSIGNMENT AND CHARACTERISTICS 

Memory is shared by COS, jobs running on the CRAY-1, dataset I/O buffers, 
and system tables associated with those jobs. COS allocates resources to 
each job as needed as these resources become available. As a job 
progresses, information is transferred between memory and mass storage. 
These transfers can be initiated by either the job or by COS. 

Figure 1-2 illustrates the assignment of memory to COS and to jobs. 
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Figure 1-1. CRAY-1 system configuration 
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Figure 1-2. Memory assignment 



MEMORY-RESIDENT COS 

COS occupies two areas of memory. The memory resident portion of the 
operating system occupying lower memory consists of exchange packages, 
the System Executive (EXEC) , the System Task Processor (STP) , and the 
Control Statement Processor (CSP) . The memory resident portion of the 
operating system occupying extreme upper memory contains station I/O 
buffers and space for the system log and dataset buffer. 



USER AREA OF MEMORY 

COS assigns every job a user area in memory, 
of a Job Table Area (JTA) and a user field. 



The user area consists 
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Job Table Area - JTA 

For each job, the operating system maintains an area in memory that 
contains the parameters and information required for monitoring and 
managing the job. This area is called the Job Table Area (JTA) . Each 
active job has a separate Job Table Area adjacent to the job's user 
field. The Job Table Area is not accessible to the user, although it may 
be dumped for analysis (see part 2, section 8). 



User field 

The usev fvetd for a job is a block of memory immediately following the 
job's JTA. The user field is always a multiple of 512 words. The 
beginning or Base Address (BA) and the end or Limit Address (LA) are 
set by the operating system. The Limit Address is specified by a 
parameter on one of the job control statements (see part 2) or by 
default. A user can request changes in field size during the course of a 
job. 

Compilers, assemblers, system utility programs, and user programs are 
loaded from mass storage into the user field and are executed in response 
to control statements in the job deck. Each load and execution of a 
program may be referred to as a joh step, 

A detailed description of the contents of the user field is given in 
Appendix A. Briefly, however, the first 200g words of the user field 
are reserved for an operating system/job communication area known as the 
Job Communication Block (JCB) . Programs are loaded starting at BA+200g 
and reside in the lower portion of the user field. The upper portion of 
the user field contains tables and dataset I/O buffers. The user field 
limit is equal to LA-1. 

Memory addresses for instructions and operands are relative to BA., The 
CRAY-l hardware adds the contents of BA to the address specified by a 
memory reference instruction to form an absolute address. A user cannot 
reference memory outside of the user field as defined by the BA and LA 
register contents; LA-1 is the user limit. (Refer to the CRAY-l Hardware 
Reference Manual or to the CRAY-l S Series Hardware Reference Manual for 
more information.) 



MASS STORAGE CHARACTERISTICS 

Mass storage for the CRAY-l/A and CRAY-l/B consists of one to thirty-two 
DD-19 or DD-29 Disk Storage Units (DSUs) . Mass storage for CRAY-l Models 
S/500 or S/1000 consists of two to thirty-two DD-29 DSUs. Mass storage 
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for CRAY-1 Models S/1200 through S/4400 consists of two to forty-eight 
DD-29 DSUs, depending on the number of I/O Processors in the I/O 
Subsystem. These devices are physically non- removable. 

All information maintained on mass storage by the CRAY-1 Operating System 
is organized into quantities of information known as datasets. In 
general, the user need not be concerned with the physical transfer of 
data between the disks and memory nor with the exact location and 
physical form in which datasets' are maintained on mass storage. COS 
translates the user's logical requests for data input and output into 
disk controller functions automatically. For the orientation of the user 
the physical characteristics of disk storage units are summarized in 
table 1-1. 



Table 1-1. Physical characteristics of disk storage units 



Feature 


DD-19 

■ 


DD-29 


Word capacity per drive 


3.723 X 10*7 


7.483 X lo"^ 


Word capacity per cylinder 


92,160 


92,160 


Bit capacity per drive 


2.424 X 10^ 


4.789 X 10^ 


Tracks per surface or 


411 


823 


cylinders per drive 






Sectors per track 


18 


18 


Bits per sector 


32,768 


32,768 


Number of head groups 


10 


10 


Latency (revolution time) 


16.7 ms 


16.7 ms 


Access time 


15 - 80 ms 


15 - 80 ms 


Data transfer rate (average 


35.4 X 10^ 


35.4 X 10^ 


bits per second) 






Longest continuous transfer 


92,160 words 


92,160 words 


per request 


(1 cylinder) 


(1 cylinder) 


Total bits that can be 


5.9 X 10^ 


5.9 X 10^ 


streamed to a unit (disk 






cylinder capacity) 
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Each disk storage unit contains a device labelr datasets, and unused space 
to be allocated to datasets. The device tahet notes usable (unflawed) 
space on the disk unit and designates one of the devices as the Master 
Device. The Master Deviee is the disk storage unit DSU containing a 
table known as the Dataset Catalog {DSC) , which contains information 
for maintaining permanent datasets. 

To the user, mass storage -permanent datasets are those datasets that may 
be assumed always present and available on mass storage. This permanence 
is achieved through techniques permitting the datasets noted in the DSC to 
be recovered or re-established in the event of system failures. Portions 
of COS, such as the loader, utility programs, the compiler, the assembler, 
and library maintenance and generation routines, reside in permanent 
datasets accessible by user jobs at any time. 

Datasets containing job input decks and output from jobs already 
terminated also reside on mass storage, and because they are listed in the 
Dataset Catalog are regarded as permanent. This designation is somewhat 
misleading since their permanence is by definition rather than by tenure 
in the system. That is, the input dataset is permanent from the time it 
is staged from the front-end system to the CRAY-1 until the job 
terminates. Output datasets being disposed to a front end are permanent 
from job termination until the disposition is completed. The permanence 
of these system-defined datasets allows them to be recovered along with 
other permanent datasets after a system failure. 

Any user job can create a mass storage permanent dataset that can be 
subsequently accessed, modified, or deleted by any other job producing the 
correct permission control words when attempting to associate it with a 
job. These permission control words are defined at the time the dataset 
is designated as permanent (that is, saved) . 

A permanent dataset ceases to exist when a user with the correct 
permission control word deletes it. This deletion notifies COS that the 
space occupied by the dataset is no longer permanent. However, the space 
is still reserved by the dataset until it is released by the user (see 
part 2 sections 3 and 5, respectively, for information on the RELEASE and 
DISPOSE control statements.) 

In addition to the various permanent datasets, mass storage is used for 
temporary datasets. A temporary dataset is created by the job using it 
and remains temporary unless it is designated as permanent or disposed to 
a front end by the job. A temporary dataset neither saved as permanent 
nor disposed of is termed a serateh dataset and ceases to exist when the 
job terminates. 
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COS allocates space to datasets by sectors as space is needed. Storage 
assigned to a single dataset can be noncontiguous and can even be on 
multiple disk units. Default and maximum sizes for datasets are defined 
by system parameters. The user has limited control over the allocation of 
storage to a dataset through the ASSIGN control statement. 



MAGNETIC TAPE CHARACTERISTICS 

An I/O Subsystem can include an Auxiliary I/O Processor (XIOP) with the 
capability of addressing up to 16 block multiplexer channels of tape 
units. Each block multiplexer channel can be attached to IBM-compatible 
control units and tape units in a variety of configurations. The block 
multiplexer channels communicate with the control units and tape units to 
allow reading and writing data that can also be read and written on 
IBM-compatible CPUs. 



Table 1-2. Physical characteristics of 200 ips, 
9-track tape devices 



Density 
(bits/inch) 


Transfer rate 
(kilo bytes/sec) 


Data/2400 ft. reel 
(mega bytes) 


% of reel 

containing 

data 


Block size 
(bytes) S 


6250 
1600 


1170 
300 


168 
43 


94 
94 


32768 
16384 



The block sizes in this table are used by the COS tape system for 
transparent-format tape datasets. 



SR-0011 



Part 1 
1-8 



J-01 



DATASETS 



All information maintained by the CRAY-l Operating System is organized 
into quantities of information known as datasets. Each dataset is 
identified by a symbolic name called a dataset name {dn) . A dataset 
can be local to a job or permanent and available to the system and other 
jobs. 



DATASET TYPES 



I Datasets are of two types: temporary and permanent, 



TEMPORARY DATASETS 

A temporary dataset is available only to the job that created it. 
Temporary datasets can be created in two ways: either explicitly by use 
of the ASSIGN control statement, or implicitly upon first reference to a 
dataset by name or unit number on an I/O request (CFT) or an OPEN macro 
call (CAL) (see part 3, section 2) . 

A temporary mass storage dataset is empty until written on. Rewind or 
backspace of the dataset is necessary before it can be read. A temporary 
dataset can be made permanent by use of the SAVE control statement. If 
the dataset is not made permanent, it will be released at job termination 
and its mass storage made available to the system. 



LOCAL DATASETS 

A dataset where a job has access is a local dataset, A local dataset 
can be temporary or permanent. Permanent datasets are made local with 
the ACCESS control statement or the ACCESS library subroutine. 

Tape datasets can be made local to a job with the ACCESS control 
statement or the ACCESS library subroutine (described in the Library 
Reference Manual, CRI publication SR-0014) . The device resource must 
also be specified on the JOB control statement. 
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MASS STORAGE PERMANENT DATASETS 

A permanent dataset is available to the system and to other jobs and is 
maintained across system startups. Permanent datasets are of two types: 
those created by SAVE requests made by the user or front-end system (user 
permanent datasets) , and input, output, or COS internal datasets (system 
permanent datasets) . 

User permanent datasets are maintained for as long as the user or 
installation desires. They are protected from unauthorized access by use 
of permission control words. 

When a user permanent dataset is accessed via an ACCESS control statement 
(see part 2, section 4) , it is treated as a local dataset by the job 
requesting access. However, it still exists as a permanent dataset on 
the system and may be used by other jobs unless unique access to that 
dataset was granted. 

System -permanent datasets relate to particular jobs or reflect the 
current operational state of COS. A job's input dataset is made 
permanent when the job is received by the CRAY-l and is deleted when the 
job terminates. Output datasets local to the job can be disposed while 
the job is running or can be made permanent when the job terminates and 
then deleted from the CRAY-l after being sent to the front-end system for 
processing. An example of a COS internal dataset is the system log. 



MAGNETIC TAPE DATASETS 

A magnetic tape dataset is available to any job declaring tape resource 
requirements on the JOB statement and specifying the appropriate 
information on its ACCESS request. 

A magnetic tape dataset can be nonlabeled (NL) , ANSI-labeled (AL) , or IBM 
standard labeled (SL) , and can be recorded or read at either 1600 or 6250 
bits per inch (bpi) . To gain access to an existing tape dataset for 
reading and/or rewriting, a volume identifier list, the correct file 
identifier (permanent dataset name) , and the desired device type must be 
specified. The volume identifier list can consist of 1 to 255 volume 
identifiers. If the PDN is omitted from the ACCESS request, the local 
dataset name is used as the file identifier. 

To gain access to a tape dataset for creating, the file identifier, 
desired device type, and the NEW parameter option must be specified. If 
no file identifier is present the local dataset name is used. If the 
volume identifier list is missing from the access request, it is called a 
non-speeifie volume soratah, A specific volume serateh occurs when 
the volume identifier list is present at the time of the access request. 
New tape datasets must be written to before a read is allowed. 
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other options describing the tape dataset are available from the access 
request. Refer to the ACCESS control statement (part 2, section 4) for 
more details. Using other parameter options allows more efficient tape 
dataset descriptions. 

COS automatically switches volumes during dataset processing and returns 
to the first volume of a multivolume dataset in response to a REWIND 
command. If a permanent write error occurs when trying to write a tape 
block for the user, COS automatically attempts to close the current 
volume and continues to the next volume. 

The COS tape system uses Buffer Memory as a tape block buffering area so 
having a COS memory circular buffer as large as or larger than a tape 
block is unnecessary. This technique can result in significant memory 
savings whenever large tape blocks are being processed and in increased 
transfer rates whenever smaller blocks are being processed. The only 
real advantage in having a large COS buffer is a reduction in the packet 
traffic (overhead) in the tape subsystem. The smallest circular buffer 
for tape datasets is 512 words (inefficient) while a buffer size greater 
than 8192 words (16 sectors) results in little performance improvement. 



EXECUTE-ONLY DATASETS 

An execute- only dataset is a user permanent dataset for which all 
unauthorized forms of examination and modification are prohibited. An 
execute-only dataset is loaded by the Control Statement Processor (CSP) 
for execution. It differs in usage from other user permanent datasets in 
several ways: 

• The accessor of the dataset cannot open the dataset for reading or 
writing, 

• While an execute-only dataset is loaded in memory, no DUMPJOB 
requests are honored. 

• The dataset cannot be staged via a DISPOSE request. 

• The dataset must be loaded by a dataset name call rather than by 
the LDR control statement. 

• The dataset cannot be dumped via PDSDUMP for archiving purposes. 

Because execute-only is a dataset state rather than a permission mode, it 
is advisable to set at minimum a maintenance permission control word to 
disallow modification or deletion of the secure dataset. 

A tape dataset cannot be made an execute-only dataset. 
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MEMORY-RESIDENT DATASETS 

Some datasets may be specified by the user as memory resident datasets. 
A memory resident dataset is wholly contained within one buffer (see BS 
parameter on the ASSIGN control statement) and remains in memory at all 
times. Such a dataset ordinarily occupies no mass storage space. A 
memory resident dataset is normally a local dataset; however, a permanent 
dataset can sometimes be declared memory resident. 

A dataset can be declared memory resident to reduce the number of I/O 
requests and disk blocks transferred. This is particularly useful for 
intermediate datasets not intended to be saved or disposed to another 
mainframe. In this case, all I/O performed on the dataset takes place in 
the dataset buffers in memory and the contents of the buffers are not 
ordinarily written to mass storage. Such a dataset cannot be made 
permanent, nor may it be disposed to another mainframe. 

Normally, a memory resident dataset is empty until written on. If an 
existing dataset is declared memory resident, it is loaded when the first 
read occurs. A user attempting to write to a memory resident dataset 
must have write permission. However, as long as the buffer does not 
appear full, no actual write to mass storage ever occurs. Therefore, 
changes made to an existing dataset declared memory resident are not 
reflected on the mass storage copy of the dataset. 

A memory resident dataset must be defined through an ASSIGN control 
statement containing the MR parameter or through an F$DNT call to the 
system. If the F$DNT call is used, the Dataset Definition List (DDL) 
supplied should specify DDMR=1. (See the description of the ASSIGN 
control statement or refer to the system calls in Appendix C for more 
information about formats.) In addition, the buffer size parameter 
should specify a buffer large enough to contain the entire dataset plus 
one block. 

If at any time the system I/O routines are called to write to the dataset 
and the buffer appears to be full, the dataset ceases to be treated as 
memory resident, the buffer is flushed to mass storage, and all memory 
resident indicators for the dataset are cleared, 

A magnetic tape dataset cannot be declared memory resident. 



INTERACTIVE DATASETS 

A dataset can be specified as interactive by a logged-on user provided 
that this feature is supported by the front end. Batch users cannot 
create interactive datasets. An interactive dataset differs from a local 
dataset in that a disk image of the dataset is not maintained. Instead, 
records are transmitted to and from a terminal attached to a front-end 
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station. Record positioning (for example, REWIND or BACKSPACE) is not 
possible. 

Interactive datasets can be created in two ways: by interactive users 
through the use of the ASSIGN control statement or through an fSdNT 
system call. 



DATASET NAMING CONVENTIONS 

The user assigns a symbolic name to each user dataset. This name, the 
local dataset namef is one through seven characters, the first of which 
can be A-z, $, @, or %; remaining characters can also be numeric. 
However, a permanent dataset name does not have this restriction; all 
characters in a permanent dataset name may be alphanumeric. Certain 
language processors may place further restrictions on dataset names. 

All datasets defined by the operating system are assigned names of the 
form %dn. Since datasets whose names begin with a $ may receive 
special handling by the system, the user should refrain from using this 
format when naming datasets. 



DATASET FORMATS 

Three dataset formats are supported for CRAY-l : blocked, interactive, 
and unblocked. 



BLOCKED FORMAT 

Blocked format is required for external types of datasets, such as user 
input and output datasets. The blocked format adds control words to the 
data to allow for processing of variable-length records and to allow for 
delimiting of levels of data within a dataset. Figure 2-1 illustrates 
the data hierarchy within a dataset. A blocked dataset can be composed 
of one or more files, which are, in turn, composed of one or more records 
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Dataset 




File 



Record 



File- 



Record2 



File. 



Record. 



Figure 2-1. Data hierarchy within a dataset 



The data in a blocked dataset can be either coded or binary. Each block 
consists of 512 words. There are two types of control words in a blocked 
dataset: block and record. 



Block control word 



The block control word (BCW) is the first word of every 512-word block. 
The format of a block control word is depicted in figure 2-2, 







8 



16 



24 



32 



40 



48 



56 



63 



Ml ///////////// 1 J ////////////////////// 1 



EN 



FWI 



BDF 



Figure 2-2. Format of a block control word 



Field 

M 

BDF 



BN 



Bits 

0-3 

11 



31-54 



Description 

Mode indicator (for block control word, M=0) 

Bad data flag; indicates the following data, up 
to the next control word, is bad. This flag is 
set by the I/O Subsystem for magnetic tape 
datasets in interchange format. 

Block number. Designates the number of the 
current data block. The first block in a 
dataset is block 0. 
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Field Bits Description 

FWI 55-63 Forward index. Designates the number of words 

(starting with 0) to the next record control 
word or block control word. 



Record control word 

A record control word (RCW) occurs at the end of each record, file, or 
dataset. The format of a record control word is illustrated in figure 
2-3. 

TRAN^^ BDF 

^ f X 16 24 32 40 48 56 63 



Ml UBC rKl/////l PFI I PFI I FWI 



Figure 2-3. Format of a record control word 

Field Bits Description 

M 0-3 Mode indicator: lOs End-of-record 

163 End-of-file 
1 7 8 End-of -da t a 

Disregarding block control words occurring at 
512-word intervals in a dataset, RCWs have the 
following logical relationship in a dataset. 

An end-of-record RCW immediately follows the 
data for the record it terminates. If the 
record is null, that is, if it contains no data, 
an end-of-record RCW can immediately follow an 
end-of-record or end-of-file RCW or can be the 
first word of the dataset. 

An end-of-file RCW immediately follows the 
end-of-record RCW for the final record in a 
file. If the file is null, that is, if it 
contains no records, the end-of-file RCW can 
immediately follow an end-of-file RCW or can be 
the first word of the dataset. 

An end-of-data RCW immediately follows the 
end-of-file RCW for the final file in the 
dataset. If the dataset is null, the 
end-of-data RCW can be the first word on the 
dataset . 
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Field 



UBC 



Bits 



4-9 



TRAN 



10 



BDF 



11 



Description 

Unused bit count. For end-of -record, UBC 
designates the number of unused low-order bits 
in the last data word of the record terminated 
by the end-of -record. For end-of -file and 
end-of -data RCWs, this field is 0. The data 
area protected by UBC must be zero-filled. 

Transparent record field. Used for an 
interactive output dataset only. If set, 
substitution of line feed for end-of-record RCWs 
is suppressed. 

Bad data flag; indicates the following data, up 
to the next control word, is bad. This flag is 
set by the I/O Subsystem for magnetic tape 
dataset s in interchange format. If flag is set, 
indicates when data was read from the device; an 
irrecoverable error was encountered in following 
data. 



PFI 



20-39 Previous file index. This field contains an 
index modulo 2**20 (20,000,0003) to the 
beginning of the file. The index is relative to 
the current block such that if the beginning of 
the file is in the same block as this ROW, the 
PFI is 0. 



PRI 



40-54 Previous record (RCW) index. This field 

contains an index modulo 2**15 (100,0008) to 
the block where the current record starts. The 
index is relative to the current block such that 
if the first word of data in this record is in 
the same block as this RCW, PRI is 0. 



FWI 



55-63 



Forward word index. This field points to the 
next control word (RCW or BCW) and consists of a 
count of the number of data words up to the 
control word (that is, if the next word is an 
RCW or BCW, FWI is 0) . 



The typical dataset has many end-of-record RCWs per block, 
dataset control words is illustrated in figure 2-4. 



An example of 
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Dataset 



Figure 2-4. Example of dataset control words 
(octal values shown) 
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Blank compression 

Blank fields may be compressed for blocked coded files. Blank field 
compression is indicated by a blank field initiator code followed by a 
count. The default blank field initiator code is the installation 
parameter I@BFI which is either an ASCII code or 7773 indicating that 
blank compression will not be done. Blank compression may be inhibited 
using an ASSIGN statement parameter or a F$DNT system 
call. A blank field of 3 through 96 characters is compressed to a 
2-character field. The count is biased by SSg; the actual count 
character is limited to 41 3 _^ ehavao-tev count <_ 1763 (the ASCII 
graphics) . 



INTERACTIVE FORMAT 

Interactive format closely resembles blocked format; however, each buffer 
begins with a block zero RCW. Each record transmitted to or from COS by 
an F$RDC or an F$WDC call must contain a single record consisting of a 
BCW, data, and an end-of-record RCW. 

Two formats for interactive output can be assigned at creation time: 
character blocked and transparent. Character blocked mode is the 
default. In character blocked mode, an end-of-record RCW is interpreted 
as a line feed or a carriage return. In transparent mode, the 
end-of-record RCW is ignored and the user is responsible for supplying 
carriage control characters. 



UNBLOCKED FORMAT 

Dataset I/O can also be performed using unblocked datasets. Any dataset 
not in COS blocked format is considered unblocked. The data stream for 
unblocked datasets does not contain CRAY-1 Operating System RCWs or BCWs. 

The system does not allocate buffers in the job's I/O buffer area for 
unblocked datasets; the user must specify an area for data transfer. 
When a read or write is performed on an unblocked dataset, the data goes 
directly to or from the user data area without passing through an I/O 
buffer. The word count of data to be transferred must be a multiple of 
512. 

Unblocked I/O cannot be performed on an interchange format tape dataset. 
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TAPE I/O FORMATS 

Tape datasets are written and read on tape volumes. A tape Volume is a 
reel of tape, also known as a section of the dataset (for example, in 
PSEC= on the ACCESS statement). Data is read or written in tape blocks, 
A tape block is a unit of data recorded on magnetic tape between two 
consecutive interblock gaps. 

The size of tape blocks can vary up to a maximum of one million bytes. 

Tape datasets can be read or written using two different formats: 
interchange or transparent. Tape datasets can be labeled or 
unlabeled. 



INTERCHANGE FORMAT 

Interchange format facilitates reading and writing tapes that are also to 
be read or written on other vendors' systems. In interchange format 
each tape block of data corresponds to a single logical record in COS 
blocked format. 

In interchange format, tape block lengths can vary up to an 
installation-defined maximum of 1,048,576 bytes (131,072 64-bit words) . 
It is recommended the maximum blocksize not exceed 100 to 200 kilobytes. 
Blocks exceeding this size may require special operational procedures 
(such as the use of special prepared tape volumes having an extended 
length of tape following the EOT reflective marker) and yield little 
increase in transfer rates or storage capacity. 

When a tape dataset is read in interchange mode, physical tape blocks are 
represented in the user's I/O buffer with block control words (BCWs) and 
record control words (RCWs) added by COS. The data in each tape block is 
terminated by an RCW. The unused bit count field in the RCW indicates 
the amount of data in the last word of the tape block that is not valid 
data. A BCW is inserted before every 511 words of data, including the 
RCWS. The formats of RCWs and BCWs are described previously in this 
section. Figure 2-5 depicts a tape dataset in interchange mode. Tape 
blocks within tape label groups are not included in this format. The end 
of the dataset is represented by an end-of-file (EOF) RCW followed by an 
end-of-data (EOD) RCW. 

When a tape dataset is written in interchange mode, the data must be in 
the I/O buffer in the user field in COS blocked format. The data in each 
logical record is written as a single tape block. BCWs and RCWs are not 
recorded on tape: block control words (BCWs) within a record are 
discarded; and the unused bits and terminating record control word (RCW) 
are also discarded. The unused bit count must be a multiple of 8. Tape 
datasets written in interchange mode must consist of a single file 
(single EOF RCW) . Multiple-file tape datasets are not supported in 
interchange mode. 
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TAPE DATA AS IT APPEARS IN I/O 
BUFFER (IN 512-WORD UNITS) 



DATA IN TAPE BLOCKS 
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Figure 2-5. Interchange- format tape dataset 
(octal values shown) 
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TRANSPARENT FORMAT 

In transparent format (disk image) , each tape block is a fixed multiple 
of 4096 bytes (512 words) based on the dataset density (that is, 16384 
bytes at 1600 BPI and 32768 bytes at 6250 BPI) . The data in the tape 
block is transferred unaltered between the tape and the I/O buffer in the 
user field; no control words are added on reading or discarded on 
writing. In transparent mode, the data can be in COS blocked format or 
COS unblocked format. 



USER LOGICAL I/O INTERFACES 

When using logical I/O, the user is never directly concerned with the 
actual transfer of data between the devices and the system buffers. 
Figure 2-6 illustrates the relationship of different levels of user 
logical I/O interfaces and routines. Figure 2-6 summarizes the request 
levels and routine calls without going into detail on the movement of 
data between the system buffers and user program areas. For details, see 
Logical I/O Macros in part 3, section 3 of this publication. 

The highest level of user interface is FORTRAN I/O statements; the lowest 
level is in the form of specially formatted requests called Exchange 
Processor requests. 

FORTRAN statements fall into two categories: formatted/unformatted and 
buffered. The formatted/unformatted statements result in calls to 
library routines $RFI through $WUF. If the dataset is blocked, these 
routines call the logical record I/O routines. The logical record I/O 
routines perform blocking and deblocking. The logical record I/O 
routines communicate with COS through the Exchange Processor F$RDC and 
F$WDC requests. 

If the dataset is unblocked, $RUA or $WUA calls the unblocked dataset 
routine $RLB or SWLB. These routines do no blocking or unblocking of 
data. The unblocked I/O routines communicate with the system through the 
F$RDC and F$WDC Exchange Processor calls. 

Buffered I/O takes a different path from formatted/unformatted I/O. 
These routines interface (through an F$BIO Exchange Processor request) to 
routines in COS that normally perform logical I/O for system tasks. 
These routines, called TASK I/O or TIO, closely resemble the logical 
record I/O routines. TIO and the logical record I/O routines make 
similar requests of circular I/O routines in COS although the mechanism 
for making these requests is different. 



Part 1 
SR-0011 2-13 J-01 



Asynchronous I/O 



Synchronous I/O 
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Figure 2-6. Relationship of levels of user I/O 
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Circular I/O routines (CIO) are the focal point for all logical I/O 
generated by COS. CIO communicates its needs for physical I/O to the 
Disk Queue Manager or Tape Queue Manager, 

A FORTRAN buffered I/O request issued for an unblocked dataset results in 
the buffered I/O routines calling the unblocked dataset routines $RLB and 
$WLB, which then process these requests. These requests are processed 
the same as formatted/unformatted requests except that buffered I/O 
requests return control to the user after initiating I/O rather than 
waiting for completion of the I/O request. For a CAL buffered I/O 
request, SCBIO is called to route the request to either the blocked or 
unblocked I/O processing routines. 

CRAY Assembly Language (CAL) I/O macros are described in part 3, section 
3 of this manual. Logical Record I/O routines and FORTRAN I/O routines 
are described in Appendix D of this manual. Refer to the FORTRAN (CFT) 
Reference Manual, CRI publication SR-0009, for a description of FORTRAN 
statements. 



DATASET DISPOSITION CODES 

Each dataset is assigned a disposi-tion eode telling the operating 
system the disposition to be made of the dataset when the job is 
terminated or the dataset is released. The disposition code is one of 
the parameters of the DISPOSE and ASSIGN control statements (see part 2). 

Each disposition code is a 2-character alpha code describing the 
destination of the dataset. The default disposition code for a dataset 
is SC (scratch) when a dataset is opened, unless the dataset is named 
$OUT, By default, COS assigns the disposition code PR (print) to $OUT 
when the dataset is created. No DISPOSE statement is required for $OUT; 
it is automatically routed back to the designated mainframe to be printed 
on a front-end designated printer. 
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DECK STRUCTURE AND JOB PROCESSING 



A joh is a unit of work submitted to the CRAY-1 computing system. It 
consists of one or more files of card images contained in a 3oh deok 
dataset , Each job passes through several stages from job entry 
through job termination. 



JOB DECK STRUCTURE 

A job originates as a card deck (or its equivalent) at a front-end 
computer system. Card images in the job deck dataset are organized 
into one or more files. Figure 3-1 illustrates a typical job deck 
consisting of a control statement file, a source file, and a data 
file. (The physical card forms for end-of-fite and end-of-data are 
defined by the front-end system.) 




Figure 3-1. Basic job deck 
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The first (or only) file of the job deck must contain the job control 
language (JCL) control statements that specify the job processing 
requirements. Each job begins with a JOB statement, identifying the 
job to the system. If accounting is mandatory in the user's system, 
the ACCOUNT statement must immediately follow the JOB statement. All 
other control statements follow the JOB statement. Control statements 
may also be grouped into control statement blocks as decribed in part 
2, section 2. The end of the control statement file is designated by 
an end-of-file (or an end-of-data if the job consists of a control 
statement file only) . 

Files following the control statement file may contain source code or 
data. These files are handled according to instructions given in the 
control statement file. 

The final card in a job deck must be an end-of-data. 



GENERAL DESCRIPTION OF JOB FLOW 

A job passes through the following stages from the time it is read by 
the front-end computer system until it completes: 

• Entry 

• Initiation 

• Advancement 

• Termination 



JOB ENTRY 

A job can enter the system in the form of a job deck submitted to a 
front-end computer system or a local or remote job entry station. The 
job is transferred to CRAY-l mass storage, where it resides until it 
is scheduled to begin processing. An entry is made in the system 
tables for the job thus making the job input dataset permanent until 
it is deleted at the completion of the job. 



JOB INITIATION 

The operating system examines the parameters on the JOB control 
statement to determine the resources needed. When system resources 
required for initiation are available, the job is initiated (scheduled 
to begin processing) . 
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Initiation of a job includes preparing a Job Table Area (JTA) and user 
field, positioning the input dataset for the first job step, and 
placing the job in a waiting queue for the CPU. 

When the CRAY-1 Operating System (COS) schedules the job for 
processing, it creates four datasets: $CS, $IN, $OUT, and $LOG. 

• $CS is a copy of the job's control statement file from $IN and 
is used only by the system; the user cannot access $CS by 
name. This dataset is used to read job control statements. 
The disposition code for $CS is SC (scratch) . 

• $IN is the job input dataset. It is identified at the 
front-end computer system by a dataset name assigned by the 
user. The job itself can access the input dataset, with read 
only permission, by its local name, $IN, or as FORTRAN unit 5. 

• $OUT is the job output dataset. The job can access this 
dataset by name or as FORTRAN unit 6. The disposition code for 
$OUT is PR (print) . 

• The job's logfile ($LOG) contains a history of the job. This 
dataset is known only to the operating system and is not 
accessible by the user. User messages can be added to the 
job's logfile with the MESSAGE system action request macro (see 
part 3) or the REMARK, REMARK2, or REMARKF subroutines in 
$FTLIB. 



JOB ADVANCEMENT 

Job advancement is the processing of a job according to the 
instructions in a control statement file. Advancement occurs as a 
normal advance or as an abort advance. 

A normal advance causes COS to interpret the next control statement in 
the job's control statement file. 

An abort advance occurs if the operating system detects an error or if 
the user requests that the job abort. An abort advance causes the 
operating system to search for and interpret the first control 
statement following the next valid EXIT control statement in the 
control statement file. EXIT statements that are within control 
statement blocks (in-line procedure, conditional, or iterative) that 
have not yet been invoked are ignored during the search for the next 
EXIT statement. 
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If the block currently being processed is a conditional block, only 
the group of control statements preceding the next conditional 
statement in the block is evaluated. For example, in the following 
sample control statement sequence, an abort advance occurs at the 
control statement THIS IS A JOB STEP ABORT CONDITION because it does 
not begin with a valid verb. Control statement interpretation resumes 
with the control statement: *. RESUME HERE. The EXIT statements 
that are included in the conditional block are ignored because they 
reside in blocks that are not executed. 



SET,J1=0. 
IF(Jl.EQ.O) 



THIS IS A JOB STEP ABORT CONDITION. 
ELSEIF (Jl.EQ.l) 



EXIT. 
ELSE. 

EXIT. 
ENDIF. 



EXIT. 

*. RESUME HERE 



JOB TERMINATION 

Output from a job is placed on system mass storage. At completion of a 
job, the operating system appends $LOG to $OUT and makes $OUT permanent. 
$IN, $CS, and $LOG are released. $OUT is renamed Jobname (from the JN 
parameter value of the JOB control statement) and is directed to the 
output queue for staging to the specified front-end computer system. 
When the front end has received the entire contents of $OUT, the system 
table entries for the dataset are deleted, and the output dataset itself 
is deleted from CRAY-1 mass storage. 

The front-end computer processes $OUT as specified by the dataset 
disposition code. 
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I If, for any reason, $OUT does not exist, $LOG is the only output returned 
at iob termination. 



JOB RERUN 

Under certain circumstances, restarting of a job from its beginning may 
become necessary or desirable. This is referred to as rerunning a job. 
Conditions causing the system to attempt to rerun a job are: 

• Operator command 

• Uncorrectable memory error 

• Uncorrectable error reading the mass storage image of a job that 
has been rolled out. Rolling out occurs because of system or user 
initiation. 

• System restart 

A user job may perform certain functions that normally make rerunning of 
a job impossible. These functions are considered nonrerunnable because 
they produce results that might cause the job to run differently if it 
were rerun. These functions include: 

• Writing to a permanent dataset 

• Saving, deleting, adjusting, or modifying a permanent dataset 

• Acquiring a dataset from a front-end system 

Ordinarily, when a job becomes nonrerunnable, it remains so. However, 
the user may specify in the program that the job is rerunnable. The user 
should do this only when changes in job results due to execution of 
nonrerunnable functions are acceptable. COS never makes a job rerunnable 
automatically. 

The user may also override system monitoring of a job rerunnability, 
regardless of what functions the job performs. This ordinarily is done 
only if the job is structured to run correctly regardless of whether 
nonrerunnable functions are performed. 
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REPRIEVE PROCESSING 

Normally, when a job step abort error occurs, control passes to the EXIT 
control statement and exit processing begins. Reprieve processing, 
however, allows the user to attempt recovery from many of the job step 
abort errors or to perform clean-up functions before continuing with the 
abort. 

Reprieve processing may also be used during the normal termination of a 
job step. In this case, control transfers to the user's reprieve code 
instead of to the next normal job step. 

Two types of error conditions are related to a job step: non-fatal and 
fatal. Non-fatal error conditions may be reprieved any number of times 
per job step by the user. Fatal error conditions can be reprieved only 
once for each type per job step. 

When requesting reprieve processing, the user selects the error 
conditions to be reprieved by setting a mask in the SETRPV subroutine or 
macro call. If a selected error condition occurs during job processing, 
the user's current job step maintains control. The user's exchange 
package, vector mask register, error code, and error class are saved and 
control passes to the user's reprieve code. (Refer to the F$RPV 
processing description in Appendix C and to Appendix F for error codes. 
Also, see description of SETRPV macro for mask values.) 



JOB LOGFILE AND ACCOUNTING INFORMATION 

For each job run, the system produces a logfile — an abbreviated history 
of the progress of the job through the system. The logfile for a job 
appears at the end of the job output and consists of a list of comments. 
Each job control statement is listed sequentially, followed by any 
messages associated with the job step. Clock time, accumulated CPU time, 
and COS information are also given for each job step. A logfile usually 
consists of the items illustrated in figure 3-2. Item 6 illustrates the 
accounting information given to the user. 
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COS 111 ASSEMBLY DRTE 06/05/82 



JOB, .JN=SflMPJOB, US=PRO.JECT2013 
iCCOUNT 

* 

*.*GErjERRTE ft PERMANENT DflTASTT. 

*. 

COPYF( 0=PERMDS ) 

FT048 - COPY OF 8 RECORDS 

COPYF,0=PERMDS, 

FT048 - COPY OF 72 RECORDS 
CSP^i^^SflUEC DN=PERMDS, ID-P2013 ) 
PDm( 5 )PD001 - SRUE PERMDS 
'"" EXIT. 

END OF .JOB 



1 FIL.es COMPLETED 



1 FILES COMPLETED 



ED=0001 COMPLETE 



® 



JOB NAME - SAMP JOB 

USER NUMBER - PROJECT20r3 

TIME EXECUTING IN CPU - 0000:00:00.0033 

TIME WAITING TO EXECUTE - 0000:00-01,0236 
TIME WAITING FOR I/O - 0000:00:00.5720 

TIME WAITING IN INPUT QUEUE -- 0000:00:00.0001 
MEMORY * CPU TIME ( MWrjS*SEC) - 0.00010 

MEMORY * I/O WAIT TIME CMWnS*.SEC) -• 0.03136 
MINIMUM MEMORY WORDS USED - 54784 

MAXIMUM MEMORY WORDS USED - 54784 

DISK SECTORS MOUED - 198 

USER I/O REQUESTS - 14 

OF'EN CALLS - 9 

CLOSE CALLS - 7 

MEMORY RESIDENT DATASETS - 

TEMPORARY DATASET SECTORS USED - 

PERMANENT DATASET SECTORS ACCESSED - 20 
PERMANENT DATASET SECTORS SAUED - 1 

SECTORS RECEIUED FROM FRONT END - 
SECTORS QUEUED TO FRONT END - 




© 

© 



Figure 3-2. Example of a job logfile 

First header line ; Installation-defined message, usually 
identifying the site and date the job was run. 

Second header line ; Installation-defined message, usually 
identifying the operating system, its current revision level, and 
the date of the last revision. 

Columns ; The leftmost column identifies the wallclock time for 
each job step and the middle column identifies the accumulated CPU 
time for the job. The rightmost column identifies a system module 
or the user as the originator of the message. All times are in 
decimal. Entries commonly noted include the following; 



CSP Control Statement Processor 

PDM Permanent Dataset Manager 

EXP Exchange Processor 

ABORT Abort Message 

USER Program in user field 
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Control statements ; Control statements are listed in the logfile 
as they are processed if requested with the ECHO statement 
described in part 2, section 1. When the job terminates, the last 
control statement processed is the last control statement printed. 
Control statements are not listed if JCL message class is disabled. 



5) Logfile messages ; Any messages related to control statement 
processing are shown below the statement. 



© 



6j Accounting information ; When a job reaches completion, COS writes 
a summary of basic accounting data onto the logfile for the job. 
All times given are in hours, minutes, and seconds (to the nearest 
ten- thousandth of a second) . The following accounting information 
is provided (in decimal) ; 

• Job name and user number 

• CPU time used by the job 

• Time waiting to execute 

• Time waiting for I/O 

• Time waiting in input queue 

• Memory usage based on the execution and I/O wait time in million 
word-seconds 

• Minimum and maximum number of memory words used 

• Number of 512-word disk blocks (sectors) moved 

• Number of user I/O requests made by the job 

• Open and close calls 

• Memory-resident datasets 

• Number of 512-word disk blocks (sectors) used for temporary 
datasets 

• Number of 512-word disk blocks (sectors) accessed and saved for 
permanent datasets 

• Number of 512-word disk blocks (sectors) received from and 
queued to the front end 

• Number of tape devices reserved; message issued only if magnetic 
tape datasets have been processed. 
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• Number of tape volumes mounted; message issued only if magnetic 
tape datasets have been processed, 

• Amount of tape data moved, expressed as a multiple of 512 words; 
message issued only if magnetic tape datasets have been 
processed. Each CRAY-1 disk sector consists of 512 words, and 
in COS blocked format each block consists of 512 words, 

• Number of tape blocks moved; message issued only if magnetic 
tape datasets have been processed. 

System Bulletin ; The system bulletin allows the installation to 
print messages in the logfile, usually about the status of the 
system environment. It is an installation-maintained message 
dataset. 
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JOB CONTROL LANGUAGE 



The job control language of the CRAY-l Operating System (COS) allows the 
user to present a job to the CRAY-l, define and control execution of 
programs within the job, and manipulate datasets associated with a job. 

The job control language is composed of control statements with each 
control statement containing information for a job step. COS initially 
creates a control statement dataset, $CS, to hold job control 
statements. Additional control statement datasets can be created via 
procedure definition (part 2, section 2) or the CALL control statement 
(part 2, section 1). 

All control statements must adhere to a set of general syntax rules. 

The syntax of a control statement is: 



verb 


sep^ 


param-i 


sep2 


param2 


• . • 


eep^ 


param^ 


term 


comments 



Every control statement consists of a verb and a terminator (term) as a 
minimum, except for the comment control statement (*) which does not 
require a terminator. Additionally, most control statements require 
parameters iparam^) and separators isep^) between the verb and 
the terminator. The maximum number of parameters (zero, one, or more) 
depends on the verb. 

The continuation separator (the caret symbol) allows a control statement 
to consist of more than one line image (80 characters) . The JOB, 
ACCOUNT, DUMP JOB, EXIT, and comment control statements cannot be 
continued. All other control statements may have any number of 
continuation card images, subject to restriction by the verb. A caret 
occurring within a literal string has no special significance. 

A comment is an optional annotation to a control statement and can be a 

string of any ASCII graphic characters. The comment follows the line 

image terminator. The control statement interpreter ignores comments. 
All comments appear in the logfile. 



Blanks are ignored unless they are embedded in a literal string, 
cannot precede the verb on the JOB control statement. 



Blanks 
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SYNTAX VIOLATIONS 

COS notes syntax violations in the system and user logfiles. If the JOB 
control statement is in error, processing of the job terminates 
immediately. If accounting is mandatory, ACCOUNT statement errors also 
cause job termination. All other syntax errors cause a job step abort 
condition, which causes the system to search for an EXIT control 
statement. A successful search resumes control statement processing with 
the job step following EXIT, if no such job step exists or if an EXIT 
statement is not found, the job is terminated. Job step abort may also 
direct control to a user-specified routine (see description of Reprieve 
processing in part 1, section 3 of this publication) . 



VERBS 

A eontrot statement verb is the first nonblank field of a control 
statement specifying the action to be taken by COS during control 
statement processing. COS recognizes three types of control statement 
verbs: system verbs, dataset name verbs {looat and system) , and 
library-defined verbs, A control statement verb cannot be continued 
across a card boundary. 



SYSTEM VERBS 

A system verb consists of an alphabetic character which can be followed by 
one through six alphanumeric characters.^ The verb requests that COS 
perform the indicated function. The system verbs are: 



* 


DELETE 


EXIT 


NORERUN 


RFL 


ACCESS 


DISPOSE 


EXITLOOP 


OPTION 


ROLLJOB 


ACCOUNT 


ECHO 


IF 


PRINT 


SAVE 


ACQUIRE 


ELSE 


lOAREA 


PROC 


SET 


ADJUST 


ELSEIF 


LIBRARY 


RELEASE 


SIMABORT 


ASSIGN 


ENDIF 


LOOP 


RERUN 


SUBMIT 


CALL 


ENDLOOP 


MODE 


REWIND 


SWITCH 




ENDPROC 


MODIFY 


RETURN 





Alphabetic characters include $, %, §, and the 26 uppercase letters A 
through Z. Alphanumeric characters include all the alphabetic 
characters and the digits through 9. 
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LOCAL DATASET NAME VERBS 

A verb that is the name of a local dataset consists of an alphabetic 
character followed by one through six alphanumeric characters.^ This 
verb requests that COS load and execute an absolute binary program from 
the first record of the named dataset. If the user job has a dataset with 
the indicated name, COS loads and executes the program from that dataset. 



LIBRARY-DEFINED VERBS 

A library-defined verb consists of one through eight characters. The 
library-defined verb is either a program^^ or procedure definition 
residing in a library that is a part of the current library searehlist . 
(The library searehlist is the order in which the content of the library 
is searched by COS. This order may be specified with the LIBRARY 
statement described in part 2, section 1.) A program in a library is an 
absolute binary program to be loaded and executed. A procedure definition 
is a group of control statements and/or data to be processed (see part 2, 
section 2) . 



SYSTEM DATASET NAME VERBS 

COS searches for a verb that is the name of a system-defined dataset in 
the System Directory Table (SDR) . A system-defined dataset name verb 
consists of an alphabetic character which can be followed by one through 
six alphanumeric characters. § The System Directory Table is a list of 
common language processors and utilities known to the system and made 
available to users at startup. The name of the program (for example, CAL, 
CFT, or DUMP) is also the name of the dataset containing the absolute 
binary of the program. 



VERB SEARCH ORDER 

When COS encounters a verb in a control statement file, it searches for a 
match to that verb in the following order: 

1. System verbs 

2. Local dataset name verbs 

3. Library-defined verbs 

4. System dataset name verbs 



Alphabetic characters include $, %, @, and the 26 uppercase letters A 
through Z. Alphanumeric characters include all the alphabetic 
characters and the digits through 9. 
Deferred implementation 
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COS first searches the list of system verbs for a match. If the verb is 
not a system verb, COS searches for a local dataset name that might match 
the verb. If the verb is not the name of a local dataset, COS searches 
each library in the library searchlist for a match. If it does not find 
a library entry that matches the verb, it searches the System Directory 
Table (SDR) for a matching system dataset name. If a match for the verb 
is not found under any of these categories, COS issues a control statement 
error. 



SEPARATORS 

A separator is a character used as a delimiter in a control statement. It 
separates the verb from the first parameter, separates parameters from 
one another, delimits subparameters, terminates verbs and parameters, and 
separates a keyword from its value in parameters having keyword form. 

The control statement separators allowed by COS are given in table 4-1. 



PARAMETERS 

A parameter is a control statement argument, the exact requirements of 
which are defined by the verb. Parameters are used in control statements 
to specify information to be used by the verb-defined process. Parameters 
that can be used with COS control statements are either positional 
or keyword. For certain verbs, a parameter value can be an expression. 
Detailed information on the use of expressions is presented later in this 
section. Parameters are separated by commas. 



POSITIONAL PARAMETERS 

A positional parameter has a precise position relative to the separators 
in the control statement. Even a null positional parameter must be 
delimited from the verb or other parameters by a separator. 

The format for a positional parameter is: 

value 
or 
value -^'.value 2'' • • • iValue^^ 

where each value^ is a string of alphanumeric characters, a literal 
string, or a null string. All positional parameters are required to be 
represented by at least one value, although the value may be null. Rules 
for strings are given later in this section. 
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Table 4-1. Control statement separators 



Function 


Character 


Examples 


Initial separator (conuna or open 

parenthesis)^ - Separates the 
verb from the first parameter 


1 

( 


VERB ,pavameter . 
VERB {parameter) 




Statement terminator (period if 
initial separator is comma; close 

parenthesis if initial separator 
is open parenthesis) § - Signifies 
end of control statement 


) 


VERB. 

VERB ,paramete r . 

VERB (parameter) 




Parameter separator (comma) - 
Indicates the end of one parameter 
and the beginning of the next 


' 


VERB {parameter ,parametev) 


Equivalence separator (equal sign) - 
Delimits a parameter keyword from the 
first parameter value for that key- 
word. Adjacent equivalence separa- 
tors are illegal. 




VERB {keyword =value ) 




Concatenation separator (colon) - 
Separates multiple parameter values 
in a keyword parameter from each 
other 


■ 


VERB ,keyword=value ^ 


'.value 2' 


Continuation character (caret) - 
Indicates that the control statement 

consists of more than one 80-character 
card; may appear anywhere after the 

initial separator 


A 


VERB { , . .parameters . 
parameters) 


..A 


Literal delimiters (apostrophes) - 
Identify the beginning and end of a 

literal string 


1 i 

(...) 


VERB {...* string ' ... 


) 


Parenthesis delimiters (open and close 
parentheses) - Indicate a group of 
characters to be treated as one value 


(...) 


VERB ,keyword= {value 


'.Value) . 



By convention in this manual, the comma and period are used as initial 
and terminator separators for all control statements except for the 
JCL block control statements (procedure definition, iterative, and 
conditional) where paired parentheses are advisable. 
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Examples of positional parameters: 

. . . ,ABCDE, . . . Parameter value is ABCDE. 

• ••//... The adjacent parameter separators 

indicate a null positional parameter 



. ..,P1:P2:P3,... 
VERBO or VERB,. 



The parameter consists of multiple values 
Positional parameter 1 is null 



KEYWORD PARAMETERS 

A keyword parameter is identified by its form rather than by its position 
in the control statement. The keyword is a string of one to eight 
alphanumeric characters uniquely identifying the parameter. Parameters 
of this type can occur in any order but must be placed after all of the 
positional parameters for the control statement; or they can be omitted. 

The format of a keyword parameter is: 

keyword 

or 
keywovd=value 

or 
keyword=value , '.value 2 : • • • •.value ^ 

where keyword is an alphanumeric string that depends on the requirements 
of the verb, and Vdlue^ is the value associated with the keyword. A 
keyword parameter can occur anywhere in the control statement after all 
positional parameters are specified. Whether or not a keyword parameter 
is required depends on the verb's requirements. If the keyword is not 
included in the control statement, a default value can be assigned by the 
prototype statement. 

Examples of keyword parameters: 

. . . ,DN=FILE1, . . . Parameter consists of keyword and value. 

...,UQ,,.. Parameter consists of keyword only. 



, DN=FILE1 : FILE2 : FILE3 , . . 



,DN=,. 



,DN=A:::B,... 



Parameter consists of keyword and list of 
values. 

Null parameter value, as if omitted from 
the statement. 

A, B, and two null parameter values are 
listed. 
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JCL PARAMETER EXPRESSIONS 

The JCL block control statements described in part 2, section 2 require a 
parameter value known as a JCL ■parameter expression. Others, such as the 
prototype statement and the definition calling statement can include 
expressions. 

An expression consists of operands and operators. Parentheses should be 
used to delimit expressions. See the description later in this section 
on the use of apostrophes and parentheses in JCL block control statements 



Operands 

Expression operands are of four types: integer constants, literal 
constants, symbolic values, and subexpressions. 

Integer constants - An integer constant is a character string of the form; 

i±\ddd, .. 
where d is a decimal digit, or 

nnn . . . B 

where n is an octal digit. 

An integer constant has an approximate decimal range 0;^| 1 1^10-^^. Range 
overflow is not detected and overflow results may be unpredictable. 

Literal constants - A literal constant is a string of one to eight 
characters of the form: 

*eoc . . . 'L 
'eoa, .. 'R 

'(3(3C. . . 'H 

where CJ is a character code with an ordinal number in the range 0408 
through IVSg. The value of a character constant corresponds to the 
ASCII character codes positioned within a 64-bit word. Alignment is 
indicated by the following suffixes: 

L Left-adjusted, zero-filled 
R Right-adjusted, zero-filled 
H Left-adjusted, space-filled 

If no suffix is supplied, H is assumed. 
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Symbolic variable - A symbolic variable is a string of one to eight 
alphanumeric characters, beginning with an alpha character, of the form: 



oca. 



A symbolic variable always has an associated value that is either 
constant or varies. COS defines a set of symbols when the job is 
initiated. Symbols are mnemonics for values maintained by COS and/or the 
user. The user may manipulate the group of symbols listed in table 4-2 
through COS control statements or through system requests. 

Certain symbols allow communication between COS and the job being 
processed. Used in the JCL block control statements defined in part 2, 
section 2, they provide the user with powerful tools for analyzing the 
progress of a job. For example, a job can request the reason for an 
abort situation and proceed, based on the reply from COS, through the use 
of conditional control statements. Symbols that are preserved over 
subprocedure calls are called local to a procedure; they are saved when a 
subprocedure is called. Those that are not preserved are global over all 
procedures and can be altered by any procedure. Constants are symbols 
that are never altered. 

Information on predefined symbols is summarized in table 4-2. 

Subexpressions - A subexpression is an expression that is evaluated so 
that its result becomes an operand. 



Operators 

Expression operators are of three types: arithmetic, relational, and 
logical. These operators are used in the FORTRAN sense. The expression 
operators are detailed in table 4-3. 

Arithmetic Operators - All arithmetic operations are performed on 64-bit 
integer quantities. Care must be used with arithmetic operators because: 

• Multiplication/division underflow or overflow of the result is not 
detected, 

• Division by zero produces a zero result. 

• Intermediate and final results are truncated. For example, 
2* (13/2) yields 12 whereas (2*13)/2 yields 13. 

Relational Operators - Relational operations return a -1 value for a TRUE 
result and a value for a FALSE result. A value produced by arithmetic 
or logical operation is considered TRUE if it is a negative value. 
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Table 4.2 Symbolic variable table 



Symbol 


Set by 


Range 


Description 


Local/Global 


J0-J7 


U 


Any 64-bit value 


Job pseudo-registers; represent 
user-alterable data local to a 
procedure. Each procedure level 
can be considered to have its 
own set of J registers. 


LOCAL 


G0-G7 


U 


Any 64-bit value 


Global job pseudo-registers; 
represent user-alterable data global 
over all procedure levels. Data can 
be passed into or returned from 
procedures with the G registers. 


GLOBAL 


JSR 


u 


Any 64-bit value 


Job status register; previous 
job step completion code 
(normally 0) 


GLOBAL 


FL 


S 


0-77777777g 


Current job field length; can 
be set with RFL statement. 


GLOBAL 


FLM 


I 


0-777777778 


Maximum job field length 


GLOBAL 


SYSID 


I 


Literal value 


COS system level of the form 
'COS X.XX' 


GLOBAL 


ssm 


S 


(l^n^e) 


Job pseudo sense switch 
settings; can be set with the 
SWITCH statement 


GLOBAL 


ABTCODE 


S 


System error codes 
(See Appendix F) 

0-nnn 


COS job abort code; abort code 
corresponding to the last job 
step abort. The abort code 
corresponds to the abort message 
number (the nnn in ABnnn) 
issued by COS. 


GLOBAL 


TRUE 


I 


-1 


True value 


GLOBAL 


FALSE 


I 





False value 


GLOBAL 


TIME 


S 


Literal value 


Time of day in the form: 

hh:mm: ss 


GLOBAL 


DATE 


S 


Literal value 


Date in the form: rm/dd/yy 


GLOBAL 


TIMELEFT 


S 


64-bit integer 


Job time remaining in milli- 
seconds as an integer value 


GLOBAL 


PDMFC 


S 


64-bit value 


Most recent user-issued Perm- 
anent Dataset Manager request. 

See Appendix C. 


GLOBAL 


PDMST 


S 


64-bit value 


Status of most recent Perm- 
anent Dataset Manager request. 
See Appendix F. 


GLOBAL 



U Alterable by user 

S Set by COS 

I System constant 
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Table 4-3. Expression operator table 



Type 


Function 


Symbol 


Results 


A 


Addition 


+ 


6 4-bit sum of operands 


A 


Unary plus 


+ 


Following integer operand is positive. 


A 


Subtraction 


- 


64-bit difference of operands 


A 


Unary minus 


- 


Following integer operand is negative. 


A 


Multiplication 


* 


64-bit product of operands 


A 


Division 


/ 


64-bit quotient of operands 


R 


Equal 


.EQ. 


True/false 


R 


Not equal 


.NE. 


True/false 


R 


Less than 


.LT. 


True/false 


R 


Greater than 


.GT. 


True/false 


R 


Less than or 
equal 


.LE. 


True/false 


R 


Greater than or 
equal 


.GE. 


True/false 


L 


Inclusive OR 


.OR. 


A 1 bit in either operand sets 
corresponding bit in the result. 


L 


Intersection 


.AND. 


A 1 bit in both operands sets 
corresponding bit in the result. 


L 


Exclusive OR 


.XOR. 


A 1 bit is set in the result if 
either (but not both) corresponding 
bit in the operands is 1. 


L 


Unary complement 


.NOT. 


A 1 bit (or 0) is set in the result 
if the corresponding operand bit is 
(or 1). 



A Arithmetic 
R Relational 
L Logical 
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Logical Operators - Logical opevat-ions return a 64-bit result. Their 
functions are performed on a bit-by-bit basis. 



Expression Evaluation 

Expressions are evaluated from left to right, honoring nested 
parentheses. The operator hierarchy is: 

1. Multiplication and division 

2. Addition, subtraction, and negation 

3. Relational operation 

4. Complement (.NOT.) 

5. Intersection (.AND.) 

6. Inclusive OR (.OR.) 

7. Exclusive OR (.XOR.) 

Parentheses can be used to change the order of evaluation. For example, 
2+3*4 is evaluated as 14 whereas (2+3) *4 is evaluated as 20. 



CAUTION 

Because COS does not check for type, the results of 
expression evaluation may not be as expected. For 
example, although both Jl=l and J2=2 are TRUE, (Jl 
.AND. J2) is FALSE. 



PARAMETER INTERPRETATION 

The cracking and interpretation of control statement parameters is 
performed by $CCS and GETPARAM. These processes are described in the 
Library Reference Manual, CRI publication SR-0014. 



STRINGS 

A string is a group of characters, delimited with either apostrophes or 
open and close parentheses, which is to be taken literally as a parameter 
value. 

Strings are normally delimited with apostrophes, in which case they are 
referred to as titeval strings. Strings delimited with parentheses are 
called paventhetio strings. Parentheses are advised to delimit strings 
in JCL block statements. See the description later in this section 
concerning the use of apostrophes and parentheses in JCL block control 
statements. 
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Characters in a string can be any ASCII graphic characters (codes 040 
through 176) . Characters otherwise recognized as separator characters 
are not evaluated as such when part of a string. 



'SEPARATORS IN STRING,.=()' 



(ABC=DEF) 



The literal string contains 
separator characters which are not 
interpreted as such. 

The parenthetic string contains an 
equal sign which is not interpreted 
as a separator. 



STRING CONSTRUCTION RULES 



Apostrophes are never treated as part of a literal string during 
evaluation except when doubled (see below) . The outermost parentheses of 
a parenthetic string are not treated as part of the string during 
parameter evaluation if preceded by the initial, parameter, equivalence, 
or concatenation separators. 



KEyW0RD= (ABC.DEF) 



ABC.DEF is the value assigned to 
KEYWORD. 



'ABC.DEF' 



ABC.DEF is the string value 



To continue literal strings across card images, place an apostrophe 
followed by a continuation character at the end of the line, and place 
the remainder of the string on the next card image preceded by an 
apostrophe. To continue parenthetic strings, place a continuation 
character at the end of the line and the remainder of the string on the 
next card image. A string can be any length, depending upon the control 
statement parameter requirements. 



. . . 'LITERAL STRING CONTINUED' 
'ACROSS CARD IMAGES' 

. . . (PARENTHETIC STRING CON- 
TINUED ACROSS CARD IMAGES) 



This is the format for continuing 
literal strings across card images 

This is the format for continuing 
parenthetic strings across card 
images. 



Two adjacent literal delimiters are interpreted as a null string 
' ' or () Both are null strings. 
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The continuation and literal string delimiters are interpreted when 
included in a parenthetic string. 

. . . : (STRING WITH 'EXTRA CLOSE PAREN )')... 

STRING WITH EXTRA CLOSE PAREN ) is 
the value of the string following 
the concatenation separator. 



...=( STRING CONTINUED ACROSS A 
CARD IMAGES) ... 



STRING CONTINUED ACROSS CARD IMAGES 
is the value of the string 
following the equivalence separator 



An apostrophe within the string is indicated by doubling it. 



•DON 



The literal string is interpreted 
as DON'T. 



APOSTROPHES AND PARENTHESES IN JCL BLOCK CONTROL STATEMENTS 

The IF, ELSEIF, EXITLOOP, PRINT, SET, procedure definition prototype, and 
definition calling statements described in part 2, section 2 can include 
expressions. Since an expression can include a literal constant which is 
delimited with apostrophes, values delimited with apostrophes in these 
statements are always treated as literal constants. Therefore, 
apostrophes should only be used to delimit literal constants, and 
parentheses should be used to delimit strings. Apostrophes in these 
statements are retained as part of the value during statement cracking, 
parameter substrition, and parameter evaluation. Also use parentheses as 
the initial and terminator separators instead of the usual comma and 
period to allow the period to be treated as an expression operator 
instead of a control statement terminator. 



IF(GO.NE. 'YES'L) 



Creates value with a literal 
constant: protects the expression 
characters during statement 
cracking so that periods are 
evaluated as expression operators 
instead of statement terminators 
and apostrophes are evaluated as 
part of literal constant instead of 
being treated as string delimiters. 



IF,GO.NE. ' 'YES'^L 



ERROR. First period processed as 
statement terminator; expression 
not evaluated. 



IF, 'GO.NE. • 'YES' 'L' 



ERROR. GO.NE. "YES' 'L is the single 
literal constant which is created. 
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More specific information about how to use apostrophes and parentheses in 
procedure definition and calling statements is presented in part 2, 
section 2, Procedure Definition. 
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INTRODUCTION AND JOB DEFINITION 



INTRODUCTION 

Job control statements identify a job to the system, define operating 
characteristics for the job, manipulate datasets, call for the loading 
and execution of user programs, call programs that perform a number of 
utility functions for the user, and define and manipulate control 
statements themselves. The first file of a job dataset contains control 
statements that are read, interpreted, and processed. 

Information on the general syntax rules and conventions for control 
statements is presented in part 1, section 4. This part describes CX)S 
control statements individually and gives examples in some cases. The 
control statements have been divided into the categories listed below. 
The Job Definition statements are described in this section; the other 
categories are defined in the remaining sections in part 2. 

• Job Definition and Control - JOB, MODE, EXIT, RFL, SWITCH, *, 
NORERUN, RERUN, lOAREA, CALL, RETURN, ACCOUNT, CHARGES, ROLLJOB, 
SET, ECHO, LIBRARY, and OPTION 

• Control Statement Blocks - In-line procedure definition, 
conditional control statement processing, and iterative control 
statement processing 

• Dataset Definition and Control - ASSIGN and RELEASE 

• Permanent Dataset Management - SAVE, ACCESS, ADJUST, MODIFY, and 
DELETE 

• Dataset Staging Control - ACQUIRE, DISPOSE, and SUBMIT 

• Dataset Utilities - COPYR, COPYF, COPYD, SKIPR, SKIPF, SKIPD, 
REWIND, and WRITEDS 

• Permanent Dataset Utilities - PDSDUMP, PDSLOAD, and AUDIT 

• Analytical Aids - DUMP JOB, DUMP, DEBUG, DSDUMP, and COMPARE, 
FLODUMP, PRINT, and SYSREF 

The relocatable and overlay loader (LDR) and the BUILD utility are also 
described in part 2. 
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JOB DEFINITION 

Several control statements allow the user to specify job processing 
requirements. Control statements defining a job and its operating 
characteristics to the operating system include the following: 

• JOB defines the job to the operating system and sets 
characteristics such as size, time limit, and priority levels. 

• MODE allows the user to set or clear the floating-point error 
interrupt flag. 

• EXIT indicates the point in a series of control statements at 
which processing of control statements resumes following a job 
step abort from a program or indicates the end of control 
statement processing. 

• RFL allows the user to request a new field length. 

• SWITCH allows the user to turn on or turn off pseudo sense 
switches. 

• * allows the user to annotate control statements with comments. 

• RERUN and NORERUN allow the user to set job rerunnability. 

• lOAREA denies or allows access to the user's I/O area. 

• CALL and RETURN allow the user to manipulate control statement 
files. 

• ACCOUNT validates the user's account number and optional password. 

• CHARGES allows the user to obtain partial or total resource 
reporting for a job. 

• ROLLJOB allows the user to protect a job by writing it to disk. 

• SET allows the user to change the value of a job control language 
(JCL) expression. 

• ECHO allows the user to control the message classes to be written 
to the user's logfile. 

• LIBRARY allows the user to specify the library datasets to be 
searched for defined procedures during job processing and in 
which order. 

• OPTION allows the user to specify user-defined options, such as 
the format of the job's listing. 
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JOB - JOB IDENTIFICATION 

The JOB control statement defines the job to the operating system. It 
must be the first statement in a control statement file. The JOB 
control statement cannot be continued to subsequent cards. No leading 
blanks are allowed on the JOB statement. JOB is a system verb. 



Format: 



JOB ,Jli=jn ,M=f I ,T=tl ,p=p ,vs=us ,oiM=olm fCL=jen ,*gn=nr. 



Parameters are in keyword form; the only required parameter is JN. 

JN=jn Job name. 1-7 alphanumeric characters. This name 

identifies the job and its subsequent output. JN is a 
required parameter, 

M=ft Memory field length, ft specifies an octal count of 

lOOOg-word (512]^q) blocks of memory to be assigned to 
the 30b. The limit address is a function of the base 
address and requested field length: 
(LA) = (BA)+fZ.*10008. 

If this parameter is omitted, the field length is set by 
the system to a value determined by an installation 
parameter . ^ 

If M is present without a value, the field size is the 
maximum amount that can be assigned. The maximum amount 
allowed is either the total amount of memory available 
after the operating system is initialized or is an 
installation-defined maximum job field length whichever is 
smaller . 

T=tt Time limit in decimal seconds after which the job is 

terminated by the system. If this parameter is omitted, 
the time limit is set to a value determined by an 
installation parameter. If T is present without a value, 
a maximum of 16,777,215 seconds (approximately 194 days) 
is allowed . 



The ft parameter on the JOB statement does not include the job's 
Job Table Area (JTA) ; space for the JTA is added by the system. The 
installation parameter, however, does include the JTA. 
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P=p Priority level at which the job enters the system. This 
parameter may assume the values of 0-15 decimal. If P is 
0, the job will not be initiated. If omitted, a value 
specified by the installation is assumed. 

US=ws User number. 1-15 alphanumeric characters. The default 
is no user number. This parameter identifies the user 
submitting the job. The user number feature is provided 
for installation accounting; specific application is 
installation-defined . 

OJM=olm Size of $OUT. olm specifies a decimal count of 512-word 
blocks. A block holds about 45 print lines. The default 
and maximum values for olm are defined by the 
installation. 

CL=jon Name of the installation-defined job class where this job 
is to be placed. 1 to 7 alphanumeric characters. The job 
is aborted if it does not fit the requirements of the 
indicated class or if the indicated class does not exist. 
The default is that the job is placed in the highest rank 
class in which it fits. 

*gn=nr Type and number of dedicated resources required by a 

job. Dedicated resource requirements are specified with 
gn and nr, 

*gn is a generic name of 1 through 7 alphanumeric 
characters. A generic name (or its installation-defined 
synonym) corresponds to a device type. For example, the 
generic name is *1600 if the job requires a tape unit 
capable of 1600 bpi. 

nr» is a positive integer; the default is 0. The job is 
aborted if it requests more resources than are dedicated 
on the JOB statement. 



Generic Name 



Synonym 
*TAPE 



Significance 



Device capable of 6250 bpi 

or 1600 bpi 

Device capable of 1600 bpi 



*6250 

*1600§ 
Example : 
*TAPE=2 requests two 6250-bpi devices for use by the job. 



§ Deferred implementation 



SR-0011 



Part 2 
1-4 



J-01 



MODE - SET OPERATING MODE 

The MODE control statement allows the user to set or clear the 
floating-point error interrupt flag in the mode (M) register in the 
exchange package for the job. This flag controls whether or not a 
floating-point error will cause an interrupt flag to be set in the flags 
(F) register. If a floating-point error condition occurs, an exit from 
the program occurs only if the floating-point error flag is set in the 
mode register. 

Format : 



MODE, Mrmode. 



Parameters: 
JA=mode 



Operating mode. May be any of the following: 

DFI, 1, or 2 Disable floating-point error interrupt 

EFI, 3, or 4 Enable floating-point error interrupt 



EXIT - EXIT PROCESSING 

An EXIT control statement indicates the point in the control istatement 
file where processing of control statements resumes following a job step 
abort from a program. If no job step abort occurs, the EXIT control 
statement indicates the end of the control statement processing. EXIT 
is a system verb. 



Format : 



EXIT. 



Parameters: none 
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RFL - REQUEST FIELD LENGTH 

The RFL control statement allows the user to request a new field 
length. RFL is a system verb. 



Format : 



RFL,M=/l. 



Parameters: 



New field length which is the octal number of lOOOg-word 
( 512^0) blocks of memory to be assigned to the job, 
excluding the Job Table Area. M is a required parameter. 
If M is present without a value, the field length is the 
maximum that can be assigned to the job. The maximum is 
either the total memory available after the operating 
system is initialized or is an installation-defined 
maximum job field length, whichever is smaller. 



SWITCH - SET OR CLEAR SENSE SWITCH 

The SWITCH control statement allows a user to turn on or turn off pseudo 
sense switches. SWITCH is a system verb. 



Format : 



SWITCH, n=a;. 



Parameters: 
n 

X 



Number of switch (1-6) to be set or cleared 

Switch position 

ON Switch n is turned on; set to 1 

OFF Switch n is turned off; set to 
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* - COMMENT STATEMENT 

The comment control statement allows the user to annotate job control 
statements with comments. A period is not required on a comment control 
statement. * is a system verb. 



Format : 



comment text 



Pa r ame t e r s : none 



NORERUN - CONTROL DETECTION OF NONRERUNNABLE FUNCTIONS 

The NORERUN control statement allows the user to specify whether the 
operating system is to recognize functions that would make a job 
rerunnable. The current rerunnability of the job is not affected. 
NORERUN is a system verb. 



SR-0011 



Part 2 
1-6.1 



J-01 



Format: 




The keywords ENABLE and DISABLE are mutually exclusive. The default for 
the system as released is NORERUN , ENABLE ; however, this is an 
installation option. 

Selecting ENABLE instructs the system to begin monitoring functions 
performed by the job and to declare the job nonrerunnable if any of the 
nonrerunnable functions are performed. 

Selecting DISABLE instructs the system to stop monitoring functions for 
nonrerunnable operations. If a job has already been declared to be 
nonrerunnable, specifying DISABLE does not make the job rerunnable again. 



RERUN - UNCONDITIONALLY SET JOB RERUNNABILITY 

The RERUN control statement allows the user to unconditionally declare a 
job to be either rerunnable or nonrerunnable. If RERUN is used to 
declare a job rerunnable, the subsequent execution of a nonrerunnable 
function may cause the system to declare the job nonrerunnable, 
depending on whether a NORERUN control statement or macro is also 
present. RERUN is a system verb. 



Format: 



RERUN I, ENABLE 
I DISABLE 



The keywords ENABLE and DISABLE are mutually exclusive. If no 
parameter is specified on the control statement, installation option 
determines if the job is to be rerunnable or not; the default for the 
system as released is RERUN , ENABLE . 

If ENABLE is selected, the system is instructed to consider the job to 
be rerunnable, regardless of what functions have been executed 
previously. 

If DISABLE is selected, the system marks the job not rerunnable 
regardless of what functions have been executed previously. 
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The RERUN control statement in no way affects the monitoring of the 
user job for nonrerunnable functions. 



lOAREA - CONTROL USER'S ACCESS TO I/O AREA 

The lOAREA control statement locks (denies the user access to) or 
unlocks (gives the user access to) that portion of the user field 
containing the user's Dataset Parameter Area (DSP) and I/O buffers. 
This area follows the High Limit Memory address (HLM) of the user 
field if locked. lOAREA is a system verb. 



Format: 



ioareaK^^^ I 

I UNLOCK J 



The keywords LOCK and UNLOCK are mutually exclusive. A parameter must 
be specified on the control statement. When the control statement is 
not used, the user's I/O area is assumed to be unlocked. 

If LOCK is selected, the system sets the limit address to the base of 
the DSPs, thereby denying direct access to the user's DSP area and I/O 
buffers. When the I/O area is locked, the library I/O routines make a 
system request to gain access to the I/O area. This introduces 
additional overhead in job processing but should prevent accidental 
destruction of the I/O area. 

If UNLOCK is selected, the system sets the limit address to the value 
specified in JCFL, allowing access to the user's DSP area and I/O 
buffers. 



CALL - READ CONTROL STATEMENTS FROM ALTERNATE DATASET 

The CALL control statement instructs COS to begin reading control 
statements from the first file of the indicated dataset. CALL may 
appear anywhere in the control statement file. Nesting of CALL 
statements is allowed to seven levels. COS reads and processes the 
control statements from the indicated dataset until it encounters an 
end-of-file or a RETURN statement. Control then reverts to the 
previous control statement dataset; the named dataset is closed prior 
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to the invocation of the procedure. The CALL statement can also 
specify values to be substituted in the procedure body. CALL is a 
system verb. 



Format 



CALL,DN=dn,CNS, 



Parameters are in keyword form. 

Dli=dn Name of dataset from which to begin reading control 

statements. This is a required parameter. 

CNS If specified, the control statement that follows is a 
pvoeeduve calling statement containing parameters for 
procedure string substitution. The format of the 
procedure calling statement depends up6n the format of 
the prototype statement. The prototype statement format 
is described in part 2, section 2. If CNS is omitted, 
no substitution is performed. CNS (Crack Next 
Statement) cannot be equated. 



RETURN - RETURN CONTROL TO CALLER 

The RETURN control statement returns control to the caller. The 
caller can be a procedure or the job's control statement file. 
Processing resumes with the caller's next control statement. A RETURN 
control statement may be embedded anywhere within the called 
procedure. However, it is not necessary to place a RETURN control 
statement at the end of the procedure because an end-of-file is 
interpreted as the control statement sequence of an EXIT, RETURN, and 
RETURN, ABORT. A RETURN encountered in the primary control statement 
file is ignored. RETURN is a system verb. 



Format s 



RETURN, ABORT. 
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Parameter; 
ABORT 



After returning to the previous control statement level, 
ABORT causes COS to issue a job step abort. ABORT is an 
optional parameter. 



ACCOUNT -• VALIDATE USER ACCOUNT 

The ACCOUNT control statement validates the user's account number and 
optional password. A job is processed only if the account number and 
password (if specified) are valid. 

The ACCOUNT statement declares the user's account number to COS. It 
must immediately follow the JOB control statement if the installation 
has defined accounting as mandatory. Only one ACCOUNT statement is 
allowed per job. The ACCOUNT control statement cannot be continued to 
subsequent cards. ACCOUNT is a system verb. 



NOTE 



The ACCOUNT control statement parameters do not appear 
with the ACCOUNT control statement in the job logfile. 



Format : 



ACCOUNT ,AC=aC ,PW=pW , 



Parameters are in keyword form. The only required parameter is AC; the 
installation defines whether a password is needed. 

AC=ac Account number. 1-15 alphanumeric characters assigned to 
the user. This number identifies the user for accounting 
purposes, and is a required parameter. The account number 
is not the same as the user number on the JOB control 
statement, unless the site chooses to use the same 
characters for both numbers. 

PW=pz<? Password. 1-15 alphanumeric characters. A password must 
be specified if the installation has made it mandatory by 
installation parameter. 
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CHARGES - JOB STEP ACCOUNTING 

The CHARGES control statement allows the user to monitor a job's usage of 
computer resources up to a specific point in a job. Hence, CHARGES can 
be used for either partial or total resource reporting. 

Partial reporting occurs when parameters are specified on the control 
statement. In this case, usage statistics for the computer resources 
specified on the CHARGES statement are obtained for the job steps 
preceding the CHARGES statement. The summary is placed in the user log 
and the system log. 

Total reporting occurs when usage statistics are obtained for all the 
resources in all the available resource groups. The summary is placed in 
the user log and the system log. 

A CHARGES statement may be placed in a job deck any number of times. If 
no CHARGES control statements are used in a job deck, computer resource 
usage statistics are gathered only upon job termination and placed in the 
I user log. 

Format: 



CHARGES , SR=optionS . 



Parameters are in keyword form. 
SR^options 



System resources used. Any one or more of the following 
groups of resources can be specified. Options are 
separated by colons. The default is a listing of the job's 
usage of resources in all of the following groups: 

JNU Job name and user number 

DS Permanent dataset space accessed, permanent dataset 
space saved, temporary dataset space used, 512-word 
disk blocks (sectors) moved, user I/O requests, 
memory resident datasets used, number of OPEN calls 
and number of CLOSE calls 

WT I/O wait time, time waiting to execute and time 
waiting for a JXT 

MM Minimum job size (words) , maximum job size (words) , 
execution- time memory integral, I/O wait-time 
memory integral, maximum field length used (words) , 
minimum field length used (words) , maximum JTA used 
(words) , and minimum JTA used (words) 



Part 2 
SR-0011 1-11 J-01 



CPU Time executing in CPU 

NBF Number of 512-word blocks (sectors) received from a 
front end and number of 512-word blocks (sectors) 
queued to a front end 

TPS Number of tape devices reserved, number of tape 
volumes mounted, amount of tape data moved 
(expressed as a multiple of 512 words) and number 
of tape blocks moved 



ROLL JOB - ROLL A USER JOB TO DISK 

The ROLLJOB control statement allows the user to protect a job by writing 
it to disk so that it can be recovered in case a system interruption 
occurs. ROLLJOB is a system verb. 

Format : 



ROLLJOB. 



Parameters: none 



SET - CHANGE SYMBOL VALUE 

The SET control statement changes the value of a specified valid job 
control language symbol. Valid symbols are those classified as alterable 
by the user (U) in table 4-2 in part 1. A job step abort occurs if a 
symbol included in a SET control statement is unknown to the system, can 
be set only by COS, or is a constant. SET is a system verb. 

Format : 



SET (symbol=expression) 



Parameters: 

syrribot A valid user-alterable symbol; symbol is a required 
parameter. 

expression 

A valid arithmetic, logical, or literal assignment 
expression. It may be delimited with parentheses to 
simplify interpretation during control statement 
evaluation, expression is a required parameter. 
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Examples: 

SET(J1=J1+1) 
This example increments the procedure-local register Jl by 1. 

SET(G1=(SYSID.AND.177777B)) 

The global register Gl is given an ASCII value which is the low-order 
two characters from the current system revision level (COS X.XX) . 

SET(G3=( (ABTCODE.EQ.74) .AND. (G2.EQ.0))) 

The global register G3 is assigned a value, depending upon the current 
values of ABTCODE and G2. 



ECHO - ENABLE OR SUPPRESS LOGFILE MESSAGES 

The ECHO control statement allows the user to control the message 
classes to be written to the user's logfile by turning the classes ON or 
OFF. ECHO can be used more than once during a job to toggle the 
printing/suppression of message classes. ECHO is a system verb. 



Format: 




Parameters are in keyword form. 






Only the messages in the classes specified are written to 
the user's logfile. If only the keyword ON or ON=ALL is 
specified, all messages are written to the logfile. 

JCL is the currently available message class. If the JCL 
message class is enabled (ON) , the JCL control statements 
are echoed on the user's logfile; if it is disabled, the 
JCL control statements are not listed on the logfile. 
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OFF=elass{, 

The messages in the classes specified are not written to 
the user's logfile. If only the keyword OFF or OFF=ALL is 
specified, all messages in defined classes are suppressed. 
OFF=JCL suppresses echoing of JCL control statements to 
logfile; however, output resulting from the execution of 
the control statements will appear. 

The keywords ON and OFF can be used in any combination: both, either, or 
neither. However, a particular class should not be included in both 
0^=classi and OFF=atass^, nor should both defaults (ON and OFF) be 
included. When the ECHO statement is not used, all messages are written 
to the user's logfile. 

Specify each class to be written or not written instead of using the 
defaults (ON and OFF) because additional classes may be added. 

When a job calls a procedure, the echo state of the job is the same upon 
return from the procedure as before, even though the procedure may use a 
different echo state. The following occurs when ECHO is used in 
conjunction with CALL and PROC: (1) The echo state of the caller (a job 
or another procedure) is saved so that on return to the caller the same 
state is in effect as before the call, and (2) When the procedure is 
called, a new echo state is created that affects only the procedure. If 
the procedure does not include an ECHO statement, the echo state of the 
caller is in effect. The echo state of the procedure can be changed 
during the procedure's execution. 



LIBRARY - LIST AND/OR CHANGE LIBRARY SEARCHLIST 

The LIBRARY control statement allows the user to specify the library- 
defined dataset names that are to be searched during the processing of 
control statement verbs. It also allows the user to list the current or 
new searchlist to the logfile for verification. 

When modifying the searchlist, the current members of the searchlist may 
be retained in the new searchlist by including an asterisk in the LIBRARY 
control statement. The asterisk corresponds to all members of the 
current searchlist in their present order. If the asterisk is omitted, 
the new searchlist contains only the library dataset names identified on 
the LIBRARY control statement. LIBRARY is a system verb. 

The default library searchlist upon job initiation consists of the single 
library dataset $PROC. 
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Format: 



LIBRARY ,BH=dn-^tdn2» . . :cZng4,V, 



DN=(in^ Library dataset names to become members of the new 

library searchlist. A maximum of 64 names (separated by 
colons) may be specified. The order in which they appear 
is the order in which they are searched. An asterisk 
included in the list means that the current searchlist 
members are to be part of the new searchlist in their 
current order. 



V 



List the current library searchlist on the logfile for 
verification. When specified along with the new 
searchlist, the new searchlist is listed. 



OPTION - SET USER-DEFINED OPTIONS 

The OPTION control statement allows the user to specify the user-defined 
options, such as the format of the job's listing. OPTION is a system 
verb. 

Format : 



OPTION, LPP=n,STAT= I °^ l. 

(OFF J 



Parameters: 



LPP=n 



STAT=pN 
lOFF 



Number of lines per page; a decimal number from through 
255. If is specified, the current number of lines per 
page is not changed. The default is an installation 
parameter . 

STAT=ON causes dataset I/O statistics for each job to 
be printed in the user logfile whenever a dataset is 
released. The statistics include dataset name, device 
name, dataset size, number of user I/O requests, number of 
512-word blocks transferred, and total time blocked for I/O 
for the dataset. No statistics are printed if STAT=OFF, 
which is the default condition. 
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JCL CONTROL STATEMENTS BLOCKS 



Certain control statements are grouped in the control statement file to 
create a control statement btook. The concepts and techniques for 
using control statement blocks assume that the reader is familiar with 
the control statements described in part 2, section 1 and has some 
experience with running simple jobs under COS control. 

Control statement blocks provide the user with the following capabilities 

• Pvooeduve definition. The user can request that a series of 
control statements and/or data be written to a library and called 
for processing at a later time. Parameters within this procedure 
can be substituted during processing. 

• Conditional control statement ■processing. The user can identify 
control statements that are to be processed only if certain 
conditions are met. 

• Iterative control statement processing. The user can identify 
control statements to be processed repetitively. 

Parentheses are advised as initial and terminator separators in the JCL 
block control statements to avoid possible errors during processing 
resulting from the unique treatment of apostrophes and parentheses in 
these statements. See part 1, section 4 for a general description of the 
use apostrophes and parentheses in the JCL block control statements. 



PROCEDURE DEFINITION 

A procedure is a sequence of control statements and/or data that has 
been saved for processing at a later time. Procedures have two formats. 

The simple procedure format consists of only the control statement body. 

The well defined procedure format consists of a prototype definition 
statement, control statement body, and optional data. It provides the 
capability of replacing values within the procedure body with values 
supplied from the procedure call. These values are called substitution 
parameters and are governed by the prototype statement of the procedure. 
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A well defined procedure can reside in a library or non-library dataset, 
A simple procedure can only reside in a non-library dataset because a 
simple procedure has no name associated with it. 

Processing (invocation) of procedures can be initiated by a procedure 
name call or with the CALL control statement (see part 2, section 1) . A 
simple procedure, because it does not have a name, must be invoked with 
the CALL control statement without the CNS parameter. A well defined 
procedure can also be invoked with the CALL statement but the CNS 
parameter must be included. The presence of CNS on a CALL statement 
indicates that the procedure to be called has a prototype statement and 
that it should be processed as such. 

Well defined procedures can be defined within the control statement 
stream {in-line definition) or as input to the BUILD utility^, when 
an in-line procedure definition is encountered in the JCL control 
statement file, it is processed and written to the system default library 
$PROC. See example 8 in this section for an example of how to create a 
user permanent procedure library. 



PRODCEDURE DEFINITION FORMAT 

A simple procedure format consists of only the control statement body. 
The format of an in-line procedure is shown in figure 2-1. The first 
control statement in an in-line procedure is PROC; the last is ENDPROC. 
A prototype statement follows PROC; it provides the name of the procedure 
and optionally a list of parameters that identify the substitution values 
within the definition body. In addition to defining the values to be 
substituted, the prototype statement parameters control the selection or 
omission of the parameters and define the default value assignments. The 
control statements and data to be processed are contained in the 
definition body. The control statements are grouped in a sequence. 

If data is included in a procedure, the data is preceded by an &DATA 
statement and follows the control statement sequence. The &DATA 
statement also includes the name of the dataset to which the data is to 
be written after processing so that programs can use the data as source 
data. 



I § BUILD currently does not suppport procedure entries in libraries. 
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A definition can be placed within a definition; such nesting can occur to 
any level. However, nested definitions are not defined until the 
outermost procedure is invoked. 



ENDPROC. 





prototype statement 



PROC. 




Figure 2-1. Procedure definition deck structure 
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PRQC - Begin procedure definition 

The PROC control statement defines the beginning of an in-line procedure 
definition block. PROC is a system verb. 



Format: 



PROC. 



Parameters: none 



Prototype statement - Introduce a procedure 

The prototype control statement has two functions: (1) to specify the 
name of the procedure and (2) to provide the formal pavametev 
specif iaat€ons that define where substitution is to occur within the 
definition body. Value substitution is described later in this section 



Format: 



name,pi,p2,P2, 



'Pri' 



name 



Procedure name; 1 through 8 alphanumeric characters. 

Formal parameter specifications, using one of the formats 
listed below. A formal parameter identifies a character 
string within the definition body. All formal positional 
parameters must precede all formal keyword parameters; if 
not, the procedure definition is in error and the job 
aborts. 



posi 



Positional formal parameter specification, or 



key i=\dvdtue \ : ikvaluel 

Keyword formal parameter specification as 
follows : 
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keyi Formal keyword parameter 

dvdlue Optional default value; this 

value is substituted if entire 
keyword parameter is omitted from 
the calling statement. 

kvdlue Optional keyed default value; 

this value is substituted if the 
keyword is present but no value 
is specified. 

Special cases: 

key^- Provides no default values and 

requires the caller to provide a 
non-null value. 

^^2/i=J Provides no default values, but 
allows the user to 
specify feez/^= or just key^. 



Procedure definition body 

The procedure definition body consists of a sequence of COS control 
statements processed as part of the current control statement file when 
the procedure is called. (It can optionally include lines of text data 
preceded in the definition body by an &DATA control statement. See 
&DATA below.) 

The prototype statement identifies character strings within the 
procedure that are to be substituted when the procedure is called. COS 
uses values supplied with the procedure call and default parameter 
values from the prototype statement to replace these strings. 

An ampersand (&) must precede each parameter to be substituted 
{suhstitu-t-lon parameter) within the definition body. If a parameter 
appears in the prototype but is not preceded by an ampersand in the 
body, substitution does not occur. 



&DATA - Procedure data 

Data may be included within the procedure definition body after the 
procedure data card. 



Part 2 
SR~0011 2-4 1-02 



The dn parameter creates a temporary dataset composed of the data 
identified in the procedure, including any substitutions resulting from 
the call. This temporary dataset allows programs such as CAL or CFT to 
use it as source data. 



Format : 



&DATA,(in 



dn 



Name of dataset to contain the data that follows; this is 
a required parameter. 



The initial separator for an &DATA statement can be a blank r comma, or 
an open parenthesis; the statement terminator can be a blank, period, or 
a close parenthesis. 

An &DATA specification cannot be continued to subsequent cards. All 
card images following an &DATA card up to the next &DATA card are 
written to the specified dataset after string substitution is 
performed. See example 7 later in this section. 



ENDPROC - End procedure definition 

The ENDPROC control statement indicates the end of an in-line procedure 
definition block. ENDPROC is a system verb. 



Format : 



ENDPROC . 



Parameters: none 



SUBSTITUTION PARAMETERS 



A character string that is eligible for substitution is listed in the 
prototype statement as a formal parameter specif iaat-ion . This name, 
when preceded by an ampersand in the definition body, indicates that a 
value is to be substituted during procedure invocation. 
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COS replaces the ampersand and parameter name with its selected value. 
If the parameter listed in the prototype statement is not preceded by an 
ampersand in the body, substitution does not occur. If two ampersands 
precede the string / one is removed and substitution is inhibited. 

Any string consisting of one through eight characters may be selected 
for substitution. Character strings to be substituted are delimited by 
any character other than numerals, alphabetics, commercial at (@) , 
dollar sign ($) , and the percent sign (%) . An ASCII underline is used 
as a string delimiter when the next character is one of these 
characters. See example 3 later in this section. COS deletes the 
underline after evaluating the string it delimits. Thus, the underline 
concatenates the strings it delimits. 



VALUE SUBSTITUTION 

When a statement in the current control statement file calls a 
procedure, COS searches the definition body for the character strings 
preceded by ampersands. For each occurrence, it substitutes the values 
supplied by either the calling statement or the prototype statement. 

In the prototype statement, parameters may be in positional or keyword 
format. 



Positional parameters 

Positional format parameters allow the user to list the strings within 
the body that can be substituted. The calling statement lists values to 
be substituted for these strings in the same order in which they are 
listed in the prototype statement. The value supplied with the calling 
statement is substituted for every occurrence of the corresponding 
formal positional parameter within the definition body. If the caller 
passes too few positional parameters, null strings are substituted for 
the remaining formal positional parameters. If too many positional 
parameters are passed, the procedure call is in error and the job aborts. 



Keyword parameters 

Keyword formal parameters are listed in any order after all positional 
parameters are given on the prototype statement and the calling 
statement. A keyword formal parameter allows the user to specify 
substitution values on the prototype statement that are to be used when 
one is not given on the calling statement. 



Part 2 
SR-0011 2-6 1-02 



If the keyword formal parameter is included in the calling statement 
with a value, that value is substituted. If the entire keyword formal 
parameter is omitted from the calling statement, the default Value on 
the prototype statement is substituted. If a default value is not 
provided on the prototype statement, the character string within the 
body corresponding to that formal parameter is not included in the 
procedure expansion. 

If only the keyword portion of the keyword formal parameter (the 
character string itself) is included in the calling statement, without a 
value assigned to it, then a keyed default value from the prototype 
statement is substituted. If a keyed default value is not provided on 
the prototype statement, again the character string within the body 
corresponding to that formal parameter is not included in the procedure 
expansion. 

A keyword parameter enclosed in apostrophes { 'KEY ' =value ) is considered 
a positional parameter. 



Positional and keyword parameters 

When supplying both positional and keyword parameters, all positional 
parameters must precede all keyword parameters; COS evaluates the call's 
positional parameters first. The end of the caller's list of positional 
parameters is signaled by the appearance of a keyword parameter, 
statement terminator, or by specifying all positionals. 



Apostrophes and parentheses 

Sometimes parameter values in a procedure definition or a procedure 
calling statement require a special format. If a literal string (a 
string delimited with apostrophes) appears in either of these 
statements, it is processed as though it were a literal constant. That 
is, all apostrophes in the value remain when the value is substituted. 
See example 5 later in this section. 

To avoid any possibility of erroneous processing, use parentheses as 
string delimiters in these statements. Outermost parentheses preceded 
by the initial, parameter, equivalence, or concatenation separators are 
removed during value substitution which delays processing of any 
separator characters in the string until the statement itself, with 
substituted values, is processed. 

This delay is also required when specifying multiple values for the 
default value and/or keyed default value parameters on a procedure 
definition statement. See examples 1, 2, 4, and 6. Parentheses are 
advised in the procedure calling statement when the use of the value in 
the procedure statements is unknown. See examples 4, 5, and 6 later in 
this section. 
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EXAMPLES 

The following examples explain the COS control statement procedure 
substitution process. 

Example 1: 

Consider a single statement procedure called LOAD which is defined as 
follows: 

Definition 

PROC. 

LOAD,NOGO=:NX,LIBRARY=($FTLIB:$SYSLIB) :MYLIB. Prototype statement 

LDR,6,N0G0,LIB=& LIBRARY. Definition body 

ENDPROC . 

The prototype statement in this example defines two formal parameters, 
both of which are in keyword format. The keyword NOGO has a null value 
when omitted from the calling statement and a value of NX when included 
on the calling statement in keyword-only format. The keyword LIBRARY 
has the default value of $FTLIB:$SYSLIB. When LIBRARY is used in the 
calling statement without a value, the keyed default value, MYLIB, is 
substituted. 

When the LOAD procedure is invoked, it expands to a single statement 
whose form depends on the choice of parameters: 

Invocation 

LOAD, NOGO. 

LOAD . 

LOAD ;LIBRARY=THISLIB . 

LOAD , LI BRARY , NOGO . 

Expansion 

LDR,NX,LIB=$FTLIB:$SYSLIB. 
LDR, ,LIB=$FTLIB:$SYSLIB. 
LDR,,LIB=THISLIB. 
LDR,NX,LIB=MYLIB. 
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Example 2: 

The following in-line procedure definition creates a procedure called 
BLDABS. 

Definition 



PROC. 

BLDABS, SOURCE, LIST, G0= 'NO':' YES ',LIB= A 

: ($SySLIB:$FTLIB) ,MAP=FULL:PART. 
REWIND, DN=$BLD: & SOURCE. 
CAL, I =& SOURCE, L=& LI ST, ABORT. 
LDR,NX,LIB=&LIB,MAP=&MAP,L=&LIST. 
REWIND, DN=$ABD:&LIST. 
SAVE , DN=$ABD , PDN=MYPROGRAM . 
IF(&GO.EQ. 'YES') 
$ABD. 
ENDIF. 
ENDPROC . 



Prototype statement 



Definition body 



Invocation 

BLDABS, WORK,, GO, LIB=VLIB2. 
Expansion 

REWIND , DN=$BLD : WORK . 
CAL , I =WORK , L= , ABORT . 
LDR,NX,LIB=VLIB2,MAP=FULL,L=. 

REWIND, DN=$ABD:. 

SAVE , DN=$ABD , PDN=MYPROGRAM . 

IFCYES'.EQ. 'YES') 

$ABD. 

ENDIF. 

Example 3 : 

This procedure exemplies the proper use of the underscore character for 
the definition of a formal parameter. It creates a procedure called 
AUDJCL. 

Definition 



PROC. 

AUDJCL, DN, LEVEL, L=$OUT:AUDLST. 
AUDIT, PDN=&DN&LEVEL_JCL,ID=JCL,L=&L. 
ENDPROC . 



Prototype statement 
Definition body 



Invocation 



AUDJCL,-, 05. 



Expansion 

AUDIT , PDN=-0 5 JCL , ID=JCL , L=$OUT . 
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Example 4: 

Parentheses are required when specifying multiple values for a single 
parameter value on a procedure definition prototype statement or on a 
calling statement. In these cases, the colon is used to separate default 
and Boolean values in a keyword parameter. For example: 

Procedure-definition prototype statement ; 

MYPR0C,P0S1,KEY=(DEF1:DEF2) : (BO 01: BOO 2) . 

Invocation : 

MYPROC, (P0S1A:P0S1B) . 

When substitution occurs during this call, P0S1A:P0S1B replaces all POSl 
occurrences within the definition body. Both values (POSIA and POSIB) 
are evaluated separately during control statement evaluation. If 
apostrophes are on the call, 'POSlArPOSlB' is evaluated as one literal 
string. 

Example 5 : 

The following procedure definition exemplifies the use of literal strings 
instead of parenthetical strings. 

Definition 

PROC. 

PURGER,PDN,ID,ED,M. Prototype 

ACCESS,DN=$PURGE,PDN=&PDN,ID=&ID,ED=&ED,M=&M,UQ,NA.| 

DELETE, DN=$PURGE,NA. ] Definition body 

ENDPROC . 

Invocation 

PURGER, 'SOURCE. MAIN' , PROJECT. 

Expansion 

ACCESS, DN=$PURGE,PDN=' SOURCE. MAIN' ,ID=PROJECT,ED=,M=,UQ,NA. 
DELETE , DN=$PURGE , NA . 
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The apostrophes remain as part of the string in the expansion. If 
parentheses had been used in the invocation instead of apostrophes for 
the permanent dataset name, (SOURCE.MAIN) , the value when the ACCESS 
statement is evaluated would be SOURCE. MAIN because the outermost 
parentheses are removed when preceded by a valid separator. This action 
would cause an error because the period in SOURCE. MAIN would be evaluated 
as a statement terminator during evaluation. 

Example 6 : 

The following example illustrates the use of parenthetical strings 
instead of literal strings in a procedure definition. 

Definition 

PROC. 

LGO,CALSORC,ABS,NLIB=$SCILIB: ($SCILIB: A 

$SYSLIB:$FTLIB) . Prototype 

CAL,I=&CALSORC. j 

LDR,NX,AB=&ABS,N0LIB=&NLIB. ) Definition body 

ENDPROC . 

Invocation 

LGO,,,NLIB. 

Expansion 

CAL,I=. 
LDR,NX,AB=,NOLIB=$SCILIB:$SYSLIB:$FTLIB. 

Parentheses were not included for the expansion of the NLIB keyed default 
value because parentheses are removed during processing when preceded by 
the concatenation delimiter (:). 

If apostrophes had been used instead of parentheses for the NLIB 
parameter value, the colons would have been ignored as separators during 
expansion. Also, apostrophes are treated as part of the value when 
included in a procedure definition prototype statement or a calling 
statement. Therefore, if apostrophes had been used, the following 
expansion would have occurred. 

CAL,I=. 
LDR,NX,AB=,NOLIB='$SCILIB:$SYSLIB:$FTLIB' . 

When the LDR statement is executed, the value assigned to the NOLIB 
parameter would be the literal string $SCILIB:$SYSLIB:$FTLIB which 
violates the syntax for the NOLIB parameter. 
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Example 7: 

Consider the following procedure definition. This procedure is used to 
retrieve specified source decks from an UPDATE program library by the use 
of the &DATA option. 



PROC. 

FETCH , PLNAME ,MASTERCH , DECKRNGE . 

ACCESS , DN=& PLNAME . 

UPDATE, I=QZRRZQ2 ,Q ,C=0 ,S , P=&PLNAME 

RELEASE, DN=QZRRZQ2 :& PLNAME. 

&DATA QZRRZQ2 

&MASTERCH_COMPILE &DECKRNGE 

ENDPROC . 



Prototype statement 
Defin-it-ion body 



Two sample invocations and their expansions follow: 



Invocation 



FETCH,COSPL,*, (ST,CT) 



Expansion 

ACCESS, DN=COSPL. 

UPDATE, I =QZRRZQ2,Q,C=0,S,P=COSPL. 

RELEASE , DN=QZRRZQ2 : COSPL . 



FETCH , FTLIBPL , * , (COS . RFD) 



(Dataset QZRRZQ2 contains: 
♦COMPILE ST,CT) 

ACCESS ,DN=FTLIBPL . 

UPDATE, I=QZRRZQ2,Q,C=0,S,P=FTLIBPL. 

RELEASE , DN=QZRRZQ2 : FTLIBPL . 

(Dataset QZRRZQ2 contains: 
♦COMPILE COS.RFD) 
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Example 8: 

Ths example illustrates one mechanism for defining and maintaining user 
procedure libraries, 

ACCESS , DN=GENLIB . 
CALL,DN=GENLIB. 

The permanent dataset GENLIB contains: 

ECHO, OFF. 

RELEASE , DN=*$PROC . 

*. 

*. Define procedure for ACCESS of commonly used ID. 

• 

PROC. 

UQ,DN,ED=:1,PDN=:GENLIB,R=:READCW,W=:WRITECW,M=:MAINCW,NA=:NA. 

ACCESS, DN=&DN,ID=MYUID,PDN=&PDN,ED=&ED,R=&R,W=&W,M=&M,NA=&NA. 

RETURN. 

EXIT. 

RETURN, ABORT. 

ENDPROC. 

*. Edit a local dataset. 

PROC. 

ED, DN,AC=: 'ACCESS* . 

IF( ' &AC' .EQ. 'ACCESS' ) 

UQ,&DN. 
ENDIF 

TEDI,DN=&DN. 
RETURN. 
EXIT. 

RETURN, ABORT. 
ENDPROC. 

*. End of definitions 
* 

• 

UQ,PROCLIB,NA. 

S AVE , DN=$PROC , PDN=PROCLIB , ID=MYUID . 

DELETE , DN=PROCLIB , NA . 

RELEASE , DN=$PROC . 

ACCESS , DN=PROCLIB , ID=MYUID . 

L IBRARY , DN=* : PROCLIB . 

ECHO, ON. 
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CONDITIONAL CONTROL STATEMENT PROCESSING 

The control statements IF, ELSE, ELSEIF, and ENDIF allow control 
statements to be placed in a conditional block structure. A conditional 
block must begin with an IF statement and conclude with an ENDIF 
statement. In addition to these two statements, it contains a control 
statement sequence that is processed only if the IF expression is true. 

Optional control statement sequences can be included within a 
conditional block using the ELSEIF and ELSE statements. If the result 
of an IF or ELSEIF expression evaluation is true, the control statement 
sequence that follows is processed and subsequent ELSE or ELSEIF 
conditions, even if true, are not processed. If the expression 
evaluates as false, the control statement sequence that follows is 
skipped. If all such sequences are skipped (all expression evaluations 
yield false), the sequence following the ELSE statement (if it exists) 
is processed. 

The conditional block is first scanned to verify the validity of the 
block's syntax. If there are any syntax errors, the block is skipped 
without being evaluated and a job step abort error occurs. This means 
that any EXIT control statements within the conditional block are 
ignored when there is a syntax error in that conditional block. This 
validation occurs when the control statement file in which it is 
contained ig invoked. 

ELSEIF and ELSE sequences are optional. Within a conditional block, 

only one ELSE sequence is permitted and it must be the last one in the 

block. There is no limit to the number of ELSEIF sequences that may be 
used in a conditional block. 

Null blocks (for example, an ELSE statement immediately following an 
ELSEIF) are ignored without comment. 

Conditional blocks can be constructed in the following ways: 

• Conditional block 

• Conditional block with ELSE 

• Conditional block with ELSEIF (s) 

• Conditional block with ELSE and ELSEIF (s) 



CONDITIONAL BLOCK 

The basic format of a conditional block, figure 2-2, begins with an IF 
statement and ends with an ENDIF statement. When the IF statement 
expression is true, the control statement sequence that follows is 
processed. If the expression is false, the control statement sequence 
is not processed. 
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ENDIF. 



control statement 
sequence 



If {expression) 



Figure 2-2. Basic conditional block structure 



IF - Begin conditional block 

The IF control statement defines the beginning of a conditional block, 
Each IF control statement must have a corresponding ENDIF control 
statement. IF is a system verb. 



Format; 



IF {expression) 



Parameters: 



expression 



A valid JCL expression (part 1, section 4). This parameter 
is required. 



ENDIF - End conditional block 

The ENDIF control statement defines the end of a conditional block. 
ENDIF is a system verb. 
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Format : 



ENDIF 



Parameters: none 

Example : 
Following is an example of the conditional block structure. 

ACCESS , DN=MYPROG . 

MYPROG. 

EXIT. 

IF(ABTC0DE.NE.21) 
*^ 

*. UNEXPECTED JOB STEP ABORT ERROR 
* ^ 

EXIT. 

ENDIF . 

In this example, if the ACCESS request or execution of MYPROG fails, the 
conditional block after the EXIT control statement is processed. The 
conditional block determines if the job step abort occurred because a 
dataset was not found, in which case the processing of control 
statements resumes after the ENDIF control statement. If this is not 
the reason for the abort, the job terminates with the EXIT control 
statement. 



CONDITIONAL BLOCK WITH ELSE 

The second conditional block structure includes the ELSE control 
statement. The control statement sequence is processed if the 
expression on the IF statement is true. If the expression is not true, 
the sequence following the ELSE statement is processed. The block 
structure is illustrated in figure 2-3. 
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control statement 
sequence 



IF {expression) 



Figure 2-3. Conditional block structure including ELSE 



ELSE - Define alternate condition 

The ELSE control statement is used to define an alternate condition. An 
IF statement, as well as any ELSEIF statements (see Conditional Block 
with ELSE and ELSEIF) , must precede the ELSE control statement. If all 
conditions specified by the IF and ELSEIF statements that precede the 
ELSE in the conditional block test as false, then the sequence of 
statements that follow the ELSE statement is executed. ELSE is a system 
verb. 

Format : 



ELSE. 



Parameters: none 
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Example : 

An example of a conditional block structure using the ELSE statement 
follows. 

ACCESS, DN=INITJCL. 
ACCESS , DN=MYPROG . 
ACCESS, DN=PROG. 
PREPROG. 
IF(JSR.NE.O) 

CALL,DN=INITJCL. 

SWITCH, 1=0N. 
ELSE. 

SWITCH, 1=0FF. 
ENDIF. 
PROG. 

After PREPROG is executed, the conditional block determines if PREPROG 
has successfully executed (by its setting of JSR) . The procedure 
INITJCL is executed and a sense switch is set if the status was bad; the 
sense switch is cleared if PREPROG executed properly. 



CONDITIONAL BLOCK WITH ELSEIF 

The third conditional block structure, shown in figure 2-4, includes one 
or more ELSEIF statements. Each logical expression on the IF and ELSEIF 
statements is tested in sequence until a true condition is found; then 
the corresponding control statement sequence is processed. 



ENDIF. 




control statement 
sequence 



E LS E I F ( expression ) 




control statement 
sequence 



'[expression) 



Figure 2-4. Conditional block structure including ELSEIF 
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ELSEIF - Define alternate condition 

The ELSEIF control statement defines an alternate condition to test if 
the previous one tested was false. The sequence of statements following 
the ELSEIF statement is executed when the ELSEIF expression is true. 
All ELSEIF control statements must precede the optional ELSE control 
statement for a conditional block. An ELSEIF statement without a 
previously processed IF statement results in a job step abort. ELSEIF 
is a system verb. 



Format: 



ELSEIF (expression ) 



Parameters: 

expression 

Any valid JCL expression (part 1, section 4) . This 
parameter is required. 

A conditional block can contain any number of ELSEIF control statements. 
The block of control statements following an ELSEIF statement is 
processed under the following conditions: 

• The expression for the IF statement is false, 

• All preceding ELSEIF statement expressions are false, and 

• The ELSEIF expression is true. 

Example : 

An example of a deck including the ELSEIF statement is: 

IF(SYSID.EQ. 'COS 1.07') 

ACCESS, DN=$FTLIBrID=V107. 
ELSEIF (SYSID.EQ. 'COS 1.08') 

ACCESS , DN=$FTLIB , ID=V108 . 
ELSEIF (SYSID.EQ. 'COS 1.09') 

ACCESS , DN=$FTLIB , ID=V109 . 
ENDIF. 
LDR,NOLIB,LIB=$FTLIB. 

This conditional block tries to access the correct version of the FORTRAN 
library, $FTLIB, for the execution of the loader that follows the 
conditional block. 
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CONDITIONAL BLOCK WITH ELSE AND ELSEIF 

The conditional block structure in figure 2-5 uses ELSEIF and the ELSE 
statements. A block can contain any number of ELSEIF statements but can 
contain only one ELSE, which must be the last conditional statement 
before the ENDIF. 




control statement 
sequence 



ELS EI F {expression) 




control statement 
sequence 



IF [expression) 



Figure 2-5. Conditional block structure including ELSEIF and ELSE 

The ELSE control statement sequence in this case is processed only if: 

• The expression on the IF statement is false, and 

• All ELSEIF statement expressions are also false. 
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Example : 

An example of this type of conditional block structure follows. 

IF(TIMELEFT.GT.175) 

IF(SYSID.EQ. 'COS 1.08') 

ACCESS ,DN=$FTLIB , ID=V108 . 
ELSEIF(SYSID.EQ. 'COS 1.09') 

ACCESS ,DN=$FTLIB , ID=V109 . 
ELSE. 

*. 

*. CURRENT SYSTEM LEVEL NOT RECENT ENOUGH 
* 

• 

EXIT. 

ENDIF. 

LDR,NOLIB,LIB=$FTLIB. 

SET,J1='YES'L. 
ELSE. 

SET,J1='N0TIME'L. 
ENDIF. 
IF(Jl.EQ.'YES'L) 

DI SPOSE , DN=RESULTS , DC=ST . 
ELSE . 

* . 

*. JOB DID NOT RUN TO NORMAL COMPLETION 
ENDIF. 
EXIT. 

This example is an expansion of the example for the third format and 
allows execution of the compiled program if there is enough time left and 
if the correct library is accessible. On a successful run, the dataset 
called RESULTS is disposed as a staged dataset. 



ITERATIVE CONTROL STATEMENT PROCESSING 

An iterative block, figure 2-6, contains a control statement sequence 
that is to be processed more than once during the processing of a 
job. It includes the LOOP, EXITLOOP, and ENDLOOP statements. Nesting 
can occur to any level. The EXITLOOP statement indicates the normal 
exit condition for the loop. If its expression is true, the loop is 
exited; if it is false, loop execution continues with the subsequent 
statements. Control returns to the beginning of the loop when the 
ENDLOOP statement is encountered. 
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ENDLOOP. 




control statement 
sequence 



EXITIOO? {expression) 




control statement 
sequence 




Figure 2-6. Iterative block structure 



Iterative blocks are prescanned for syntax errors before actual 
processing begins. Any errors in the block structure cause a skipping 
of that block followed by a job step abort. If an iterative block is 
included within a conditional block, it must be totally contained 
within that block. 



LOOP - BEGIN ITERATIVE BLOCK 

The LOOP control statement is required to define the beginning of an 
iterative block. An ENDLOOP control statement is required in the same 
procedure dataset to terminate the iterative block. LOOP is a system 
verb. 



Format: 



LOOP 



Parameters 



none 
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ENDLOOP - END ITERATIVE BLOCK 

The ENDLOOP control statement terminates an iterative control 
statement block. If an ENDLOOP control statement occurs in a 
procedure dataset without a preceding LOOP statement, a job step abort 
occurs. Execution of the ENDLOOP statement results in control being 
passed to the preceding LOOP statement which begins another iteration 
of the loop. 



Format: 



ENDLOOP . 



Parameters: none 



EXITLOOP - END ITERATION 

The EXITLOOP control statement defines the condition (s) under which 
the control statement block iteration is to end. If its expression is 
true, the loop is exited; if it is false,' the control statements which 
follow are executed. 

An EXITLOOP statement that appears outside of an iterative block 
causes a job step abort. When nesting iterative control statement 
blocks, the EXITLOOP control statement defines the exit conditions for 
only the most immediate iterative block. EXITLOOP is a system verb. 



Format: 



EXITLOOP. 



or 



EXITLOOP {expression } 



Parameters: 
expr'ess^on 



Optional valid JCL expression (part 1, section 4). If 

omitted, an unconditional exit from the iterative block 
occurs. 
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Example : 

The following example merges the two datasets DSINl and DSIN2 for 60 
records. 

SET,J1=0. 

SET,J2=60. 

LOOP. 

EXITLOOP(J2.EQ.O) 
IF(Jl.EQ.O) 

COPYR, I=DSIN1 ,0=OUTDS . 
SET,J1=1. 
ELSE. 

COPYR, I=DSIN2,0=0UTDS. 

SET,J1=0. 
ENDIF. 

SET,J2=J2-1. 
ENDLOOP. 
REWIND , DN=DSIN1 : DSIN2 : OUTDS . 
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DATASET DEFINITION AND CONTROL 



Datasets can be defined and managed by the user via three dataset control 
statements: ASSIGN, ACCESS, and RELEASE. 

• ASSIGN creates a dataset on mass storage and assigns dataset 
characteristics for tape and disk, 

• ACCESS (defined in part 2, section 4) makes an existing disk or 
tape permanent dataset local to a job or can be used to create a 
dataset on magnetic tape; ASSIGN assigns tape dataset 
characteristics. 

• RELEASE relinquishes access to the named dataset for the job. 



ASSIGN - ASSIGN MASS STORAGE OR MAGNETIC TAPE DATASET CHARACTERISTICS 

The ASSIGN control statement creates a mass storage dataset and assigns 
dataset characteristics for tape and mass storage. If an ASSIGN is used 
for dataset creation, it must appear prior to the first reference to the 
dataset; otherwise, the characteristics are defined at the first 
reference. If an ASSIGN is used for a tape dataset, it must follow the 
tape ACCESS request. ASSIGN § is a system verb. 

Format: 



ASSIGN , DN=dn , S=Si:se , BS=blk , DV=Wy , DT=cit , DF=d/, 



KDM,\J,MRflM=lm,DC=do,BFl^bfi,h=un, 



Parameters are in keyword form. The only required parameter is DN. 

DN=dn Local dataset name. 1-7 alphanumeric characters, the first 
of which is A-z, $, %, or @; remaining characters may also 
be numeric. DN is a required parameter. 



§ ASSIGN does not create a dataset which the CFT 1.10 OPEN statement 
recognizes as existing. 
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S=s-ize Dataset size. Octal number of sectors (lOOOg-word 

blocks) to be reserved for the dataset. If the dataset 
size is not given, the disk space for the dataset is 
dynamically allocated as needed. This parameter applies to 
mass storage datasets only and is ignored when used for 
magnetic tape datasets. 

BS=btk Buffer size. Number of lOOOg-word blocks to be reserved 

for user buffer. The default number of blocks is set by an 
installation parameter. BS generates an error if the U 
parameter is specified (indicating unblocked dataset 
structure) . 

DV^tdv Logical device on which dataset is to begin. If a logical 
device name is not given, one is chosen by the system. 
Consult the on-site analyst for possible logical device 
names. This parameter applies to mass storage datasets 
only and is ignored when used for magnetic tape datasets. 

T)T=dt Device type. The allowable device types are CRT and MS. 

MS is the default. This parameter applies to mass storage 
datasets only and is ignored when used for magnetic tape 
datasets. 

I>F=df Dataset format. This parameter is used only on output; it 

is valid only when DT=CRT. This parameter applies to mass 
storage datasets only and is ignored when used for magnetic 
tape datasets. Two formats are supported: 

CB Character blocked. End-of-record RCWs are converted 
to line feeds. This is the default. 

TR Transparent. End-of-record RCWs are not converted 
to line feeds. The user is responsible for 
inserting line feeds. 

RDM Random dataset. If the RDM parameter is present, the 

dataset is to be accessed randomly. If the RDM parameter 
is not specified, the dataset is accessed sequentially. 
This parameter applies to mass storage datasets only and is 
invalid for magnetic tape datasets. 

U Unblocked dataset structure. If the U parameter is 

present, the dataset is not in COS-defined blocked format. 
If the U parameter is absent, the dataset is a COS blocked 
dataset. (See part 1, section 2 for information on 
unblocked dataset format.) This parameter is invalid for 
interchange format tape datasets. 
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MR Memory resident dataset. If this parameter is present, the 
system I/O routines write the buffers to the disk only if 
they become full. If the MR parameter is absent, the 
dataset is not a memory resident dataset. MR generates an 
error if the U parameter is specified. This parameter 
applies to mass storage datasets only and is invalid for 
magnetic tape datasets. 

LM=Z.W2 Maximum size limit for this dataset. Im specifies a 

decimal count of 512-word blocks. The job step will be 
aborted if this size is exceeded. The default and maximum 
dataset size limits are set by an installation parameter. 
This parameter applies to mass storage datasets only and is 
ignored for magnetic tape datasets. 

DC=de Disposition code. Disposition to be made of the dataset at 

job termination. This parameter applies to mass storage 
datasets only and is ignored for tape datasets. The 
default is SC. 

do is a 2-character alpha code describing the destination 
of the dataset as follows: 

IN The dataset is placed in the input queue of the 
default destination station. 

ST Stage to mainframe. Dataset is made permanent at 
the mainframe of job origin. 

SC Scratch dataset. Dataset is deleted. 

PR Print dataset. Dataset is printed on printer at the 
mainframe of job origin. 

PU Punch dataset. Dataset is punched on any card punch 
available at the mainframe of job origin. 

PT Plot dataset. Dataset is plotted on any available 
plotter at the mainframe of job origin. 

MT Magnetic tape. Dataset is written on magnetic tape 
at the mainframe of job origin. 

BFI=Z?/i Blank field initiation. Octal representation of ASCII code 
which indicates the beginning of a sequence of blanks. 
BFI=OFF means that blank compression is inhibited. The 
default code is 33g (ASCII ESC code) but may be changed 
by an installation parameter. 
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A=wn Unit name. Unit names allow the user to refer to a dataset 
from a FORTRAN program. Each unit name is 4 characters in 
the form FTxx, where xx is the unit number specified. The 
unit number is an integer value in the range 0-102. 
However, because unit numbers 100, 101, and 102 are 
reserved for system use, a user may designate unit numbers 
0-99. 

Use of this parameter associates the designated unit with 
the dataset specified by the DN parameter. At job 
initiation, unit PT05 is associated with dataset $IN and 
unit FT06 is associated with dataset $OUT, Unit names 
should not be used as dataset names. 



NOTE 

If a dataset is used in place of a unit name or 
vice versa, FORTRAN *77 auxiliary statements 
(that is, OPEN, CLOSE, and INQUIRE) may produce 
unpredictable results. 



RELEASE - RELEASE DATASET 

The RELEASE control statement relinquishes access to the named datasets 
for the job. If a dataset is not permanent and its disposition code is 
SC (scratch), the mass storage assigned to the dataset is released to the 
system. If the dataset is to be staged, the dataset is entered in the 
output queue for staging to the default destination station. An 
end-of-data is written to a permanent dataset when it is released if the 
dataset is blocked sequential and the previous operation was a write. 



Format : 



RELEASE, DN=dn 2^ :dn2: . . . idnQ,EOl,D^. 



§ Deferred implementation 
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Parameters: 



DN=<in^ Name of dataset to be released. A maximum of eight 
datasets may be specified. 

HOLD§ Hold generic device; do not return it to the system pool. 
This parameter applies to magnetic tape datasets only and 
is ignored for mass storage datasets. 



§ Deferred implementation 
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PERMANENT DATASET MANAGEMENT 



Permanent dataset management provides methods for creating, protecting, 
and accessing datasets assigned permanently to mass storage or magnetic 
tape. Such datasets cannot be destroyed by normal system activity, 
deadstarting, restarting, or engineering maintenance. 

The user can manage user permanent datasets only; system permanent 
datasets are not directly accessible by the user. (See part 1, section 2 
for a description of the types of datasets.) 

The user manages user mass storage and magnetic tape permanent datasets 
by sending requests to the system through the control statements 
described below. Mass storage datasets are controlled by the Permanent 
Dataset Manager using the CRAY-1 resident Dataset Catalog (DSC) ; magnetic 
tape datasets are processed by the Tape Queue Manager (TQM) . 

• SAVE enters a dataset' s identification and location in a 
system-maintained Dataset Catalog. Datasets recorded in the 
Dataset Catalog via a user SAVE request are user permanent 
datasets and are recoverable at deadstart. SAVE applies to mass 
storage datasets only; it is ignored for tape datasets. 

• ACCESS causes a user permanent dataset to be assigned (made local) 
to a job. The usage (reading or writing, for example) of a 
dataset is determined by permissions granted when the dataset is 
accessed. ACCESS is also used to create a dataset on magnetic 
tape or to obtain an existing one. 

• ADJUST changes the size of a user permanent dataset in the Dataset 
Catalog. ADJUST applies to mass storage datasets only; it is 
ignored for tape datasets since their size is automatically 
changed when the output tape dataset is closed. 

• MODIFY changes established information for an existing user 
permanent dataset in the Dataset Catalog. MODIFY applies to mass 
storage datasets only; it is ignored for tape datasets. 

• DELETE causes removal of a saved dataset from the Dataset Catalog. 
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SAVE - SAVE PERMANENT DATASET 

The SAVE control statement makes a local dataset permanent. Saving a 
dataset consists of making an entry in the DSC. A permanent dataset is 
uniquely identified by permanent dataset name, user identification, and 
edition number. SAVE is a system verb. The SAVE statement is ignored 
when used for magnetic tape datasets. 

SAVE has a twofold function: 

• Creation of an initial edition of a permanent dataset 

• Creation of an additional edition of a permanent dataset 

A maintenance control word controls the creation of additional 
editions of an existing permanent dataset. Thus, to create a 
subsequent edition of an existing permanent dataset, the user must 
match the maintenance control word of the oldest existing edition. 
Read and write control words specified on the oldest existing edition 
of a permanent dataset apply to all subsequent editions of that 
dataset. 

Under the appropriate conditions, SAVE forces any unwritten data to 
disk to ensure that all of the dataset is made permanent. Since this 
situation occurs when the dataset has been recently written to but not 
yet closed, SAVE will attempt to close the dataset. The specific 
conditions which the dataset must meet are described under the SAVE 
macro (part 3, section 4) . 



Format ; 



SAVE,DN=dn,PDN=pdn,ID=wid,ED=0d,RT=7't,R=r'd,W=&?t, 



M=mn,UQ,NA,EXO{=°^ 
OFF 



Parameters are in keyword form; the only required parameter is DN. 

DN=<in Name of a dataset that is local to the job. This dataset 
may be closed before the dataset is made permanent. 

PDN=p(in Permanent dataset name. 1-15 characters assigned by the 
dataset creator. This is the name that is saved by the 
system. Default value is dn. 
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lD=uid User identification. 1-8 alphanumeric characters assigned 
by the dataset creator. The default is no user ID. 

ED-ed Edition number. A value from 1-4095 assigned by the dataset 

creator. The default value is: 

• One, if a permanent dataset with the same PDN and ID 
does not exist, or 

• The current highest edition number plus one, if a 
permanent dataset with the same PDN and ID does exist. 

RT=rt Retention period. User-defined value from 0-4095 specifying 

the number of days a permanent dataset is to be retained by 
the system. The default value is an installation-defined 
parameter . 

R=vd Read control word. 1-8 alphanumeric characters assigned by 

the dataset creator. The read control word of the oldest 
existing edition of a permanent dataset applies to all 
subsequent editions of that dataset. The default is no read 
control word. 

VI=wt Write control word. 1-8 alphanumeric characters assigned by 

the dataset creator. The write control word of the oldest 
existing edition of a permanent dataset applies to all 
subsequent editions of that dataset. To obtain write 
permission, the user must also have unique access (UQ) to 
that dataset. The default is no write control word. 

M=mw Maintenance control word. 1-8 alphanumeric characters. The 
maintenance control word must be specified if a subsequent 
edition of the same permanent dataset is saved. The default 
is no maintenance control word. 

UQ Unique access. If the UQ parameter is specified, only this 
job may access the permanent dataset at the completion of 
the SAVE function. Otherwise, multiuser access to the 
permanent dataset is granted. 

NA No abort. If this parameter is omitted, an error causes the 
job to abort. 

EXO{=___} Execute-only dataset. This parameter sets or clears the 
execute-only status of the dataset. EXO only or EXO=ON 
causes the dataset to be saved as execute-only. EXO=OFF or 
omission of this parameter causes the dataset to be saved as 
a non-execute-only dataset. 



off) 
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NOTE 

When processing for the SAVE request is 
complete, all forms of examination of this 
dataset are prohibited if EXO=ON. 



ACCESS - ACCESS PERMANENT DATASET 

The ACCESS control statement makes an existing permanent dataset local to 
a job and can be used to create a tape dataset. Following the ACCESS 
statement, all references to the permanent dataset must be by the local 
dataset name specified by the DN parameter. ACCESS assures that the user 
is authorized to use the permanent dataset. The ACCESS control statement 
must precede the ASSIGN control statement or the open call for the 
dataset. ACCESS is a system verb. 

The user need not access a permanent dataset entered into the System 
Directory (SDR) . A tape dataset cannot reside in the SDR. A basic set of 
datasets is entered into the System Directory when the operating system is 
installed. These datasets include the loader, the CFT compiler, the CAL 
assembler, UPDATE, BUILD, and system utility programs such as copies and 
dumps. Other datasets can be entered into the System Directory according 
to site requirements. 



Format : 



ACCESS, DN=dn,PDN=pdn,ID=Mid,ED=ed,R=r»d,W=z«?t,M=mw,UQ,LE,NA, 



CS=cs , DF=d/,DT=cft , FSEC=feeo , LB=ZZ?,MBS=m2?S ,NEW, XDT=2/2/cZdd, 



RT-rt,^OL=^voli:vot2i» • .yoZ^,CT=c^,RF=r»/,RS=r»s, 
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Parameters are in keyword form; DN is the only required parameter for mass 
storage datasets to make an existing permanent dataset local to a job. 

DN=dn Local dataset name by which the permanent dataset is to be 
known. This is a required parameter. 

PDN=pdn Name of a permanent dataset being accessed and already 
existing in the system. The default value is dn. The 
name can be 1-15 characters for mass storage datasets; it 
can be 1-44 characters for tape datasets. For a labeled 
tape dataset, the right-most 17 characters of the PDN must 
match the file identification field of the HDRl label. 

lD=u'td User identification. 1-8 alphanumeric characters. If uid 
was specified at SAVE time, the ID parameter must be 
specified on the ACCESS control statement. The default is 
no user ID. This parameter applies to mass storage datasets 
only; it is ignored for magnetic tape datasets. 

ED=ed Edition number of permanent dataset being accessed; a value 
from 1-4095 was assigned by the dataset creator. If the ED 
parameter is not specified, the default is the highest 
edition number known to the system (for this permanent 
dataset) . This parameter applies to mass storage datasets 
only; it is ignored for magnetic tape datasets. 

R=rd Read control word as specified at SAVE time. 1-8 

alphanumeric characters assigned by the dataset creator. 
The read control word of the oldest existing edition of a 
permanent dataset applies to all subsequent editions of that 
dataset. The default is no read control word. To obtain 
read permission, this parameter must be specified on the 
ACCESS control statement if a read parameter was specified 
when the dataset was saved. This parameter applies to mass 
storage datasets only; it is ignored for magnetic tape 
datasets. 

W=wt Write control word as specified at SAVE time. To obtain 
write permission, this parameter must be specified in 
conjunction with a UQ parameter on the ACCESS control 
statement if a W parameter was specified when the dataset 
was saved. This parameter is required prior to an ADJUST 
and applies to mass storage datasets only; it is ignored for 
magnetic tape datasets. 
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M=mn 



UQ 



Maintenance control word as specified at SAVE time. This 
parameter is specified in conjunction with a UQ parameter on 
an ACCESS control statement if the dataset is to be 
subsequently deleted. That is, maintenance permission is 
required to delete a dataset. This parameter applies to 
mass storage datasets only; it is ignored when used for 
magnetic tape datasets. 

Unique access. If the UQ parameter is specified and the 
appropriate write or maintenance control words are 
specified, then write, maintenance, and/or read permission 
may be granted. If UQ is not specified, then multiuser read 
access is granted by default (if at a minimum, the read 
control word is specified) . UQ is required to delete a 
permanent dataset using the DELETE control statement. This 
parameter applies to mass storage datasets only; it is 
ignored for magnetic tape datasets. 



LE^ 



Lowest edition number. If the LE parameter is specified, 
the lowest edition number known to the system for this 
dataset is accessed. LE must not be equated with a value 
and cannot be specified in conjunction with the ED 
parameter. This parameter applies to mass storage datasets 
only; it is ignored when used for magnetic tape datasets. 



NA 



No abort. If this parameter is omitted, an error causes the 
job to abort. 



CS=es Character set of tape dataset, for data only. This 

parameter applies only to tape datasets; it is ignored when 
used for mass storage datasets. 

AS ASCII; default. 

SL EBCDIC 



BF=df 



Tape dataset format. This parameter applies only to tape 
datasets; it is ignored when used for mass storage datasets. 

IC Interchange format 

TR Transparent format; default. 



§ Deferred implementation 
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DT=dt Tape dataset generic device name or synonym. This parameter 

is required for tape datasets. 

Generic Name Synonym Significance 

*6250 *TAPE Device capable of 6250 bpi 
*1600 Device capable of 1600 bpi; 

also used to declare density 
when writing 

FSEC^fseo File section number; a numeric field from 1 through 9999 
that specifies the volume in the tape dataset. The first 
section (or volume) of a tape datatset is numbered 0001. 
The default is 1. For example, to access a tape dataset 
starting with the eighth section, specify FSEC=8 on the 
ACCESS call. This parameter applies only to tape datasets; 
it is ignored when used for mass storage datasets. 

LB=tb Tape dataset label type. This parameter applies only to 

tape datasets; it is ignored when used for mass storage 
datasets. 

BLP Bypass label processing^ 

SL IBM standard-labeled tapes 

NL Non labeled tapes; default 

AL ANSI standard labeled tapes 

MBS^mbe Maximum tape block size; that is, the number of bytes in the 
largest tape blocks to be read or written. The maximum size 
allowed at the installation and the default are specified as 
installation parameters. This parameter applies only to 
tape datasets; it is ignored when used for mass storage 
datasets . 

NEW Tape dataset is to be created; the dataset must be written 
starting at the beginning of information. This parameter 
applies only to tape datasets; it is ignored when used for 
mass storage datasets. 

XDT=i/yddd Expiration date. Indicates the date on which this tape 

dataset may be overwritten, yy specifies the year and is 
a number from 0-99. ddd specifies the day in the year and 
is a number from 001 through 366. This parameter applies 
only to tape datasets; it is ignored when used for mass 
storage datasets. 



§ Deferred implementation 
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RT=r»t^ Retention period. User-defined value from 1 through 

4095 specifying the number of days a permanent dataset is 
to be retained by the system. Similar to the XDT parameter 
but allows the user to specify relative expiration date. 
The default value is an installation-defined parameter. 

VOL=DcZ^ Volume identifier; a list of 6-character alphanumeric 
volume identifiers comprising the tape dataset. The 
maximum number of volume identifiers per dataset is an 
installation parameter. 

The following tape dataset parameters specify that record and data format 
conversion are to be performed at run time on the tape dataset. 

CT=ot^ Tape dataset conversion type, ct is a 3-character code 
describing the machine internal data representation. 

IBM IBM 370 and compatible internal data representation 

This parameter is required if run-time record and data 
format conversion are performed; default is no conversion. 
This parameter applies only to tape datasets; it is ignored 
when used for mass storage datasets. Specifying this 
parameter converts data on the tape from 32-bit IBM 
internal representation to 64-bit internal CRAY-1 
representation. Real numbers and integers are converted. 

RF=r»/^ Tape dataset record format, rf is a 1- to 
8-character code describing the record type. 

U IBM U (undefined) format; default if CT=IBM 

F IBM F (fixed) format 

FB IBM FB (fixed block) format 

V IBM V (variable) format 

VB IBM VB (variable block) format 

VBS IBM VBS (variable blocked spanned) format 

RS=r»e Tape dataset record size, rs is the decimal length of 

the record expressed in units depending upon the conversion 
type; if CT=IBM, rs is the record size expressed as a 
decimal number of 8-bit byte units. If the rf parameter 
is F or FB, the RS parameter is required; if rf is V, VB, 
or VBS, the RS parameter is optional; if rf is U, the RS 
parameter is not pertinent as the U record format does not 
contain records. 



§ Deferred implementation 
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ADJUST - ADJUST PERMANENT DATASET 

The ADJUST control statement changes the size of a mass storage permanent 
dataset; that is, it redefines the size of the dataset. When a permanent 
dataset is overwritten, and the dataset size changes, issuing an ADJUST 
statement informs the system of the dataset' s new size. An ADJUST of a 
permanent dataset may be issued if the dataset has been previously 
accessed within the job with write permission. ADJUST is a system verb. 

Under the appropriate conditions, ADJUST forces any unwritten data to 
disk to ensure that all of the dataset is made permanent. Since this 
situation occurs when the dataset has been recently written to but not 
yet closed, ADJUST will attempt to close the dataset. The specific 
conditions that the dataset must meet are described under the ADJUST 
macro (see part 3) . 

The ADJUST statement is ignored when used with magnetic tape datasets. 
Format : 



ADJUST,DN=dn,NA. 



Parameters: 
DN=dn 

NA 



Local dataset name of a permanent dataset that has been 
accessed with write permission. This dataset may be closed 
before the ADJUST statement is processed. 

No abort. If this parameter is omitted, an error causes the 
job to abort. 



MODIFY - MODIFY PERMANENT DATASET 

The MODIFY control statement changes permanent dataset information 
established by the SAVE function or a previously executed MODIFY 
function. A permanent dataset must be accessed with unique access (UQ) 
and all permissions before a MODIFY of a permanent dataset can be issued. 
MODIFY is a system verb. 

Once a permanent dataset exists, the read, write, and maintenance control 
words apply to subsequent editions of that permanent dataset. Therefore, 
permission control words can be modified only for a permanent dataset 
having a single edition. MODIFY applies to mass storage datasets only; it 
is ignored for tape datasets. 
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Format : 



MODIFY , DN=dn ,PDN=pdn , lD=uid,ED=ed,R'J!=rt , R=rd, 



W=Zx?t , M=mn, NA , EXO I =°N 

OFF 



Parameters are in keyword form; the only required parameter is DN, 

DN=(iw Local dataset name of a permanent dataset that has been 

accessed with all permissions. DN is a required parameter, 

PDN=p(in New permanent dataset name to be applied to the existing 
dataset. If this parameter is omitted, the existing 
permanent dataset name is retained. 

ID=wid New user identification, to be applied to the existing 

permanent dataset. 1-8 alphanumeric characters. If this 
parameter is omitted, the existing user ID is retained. If 
this parameter is present without a value, user 
identification is established as binary zeros. 

ED=ed New edition number to be applied to the existing permanent 

dataset. If this parameter is omitted, the existing edition 
number is retained. 

RT-rt New retention period to be applied to the existing permanent 

dataset. If this parameter is omitted, the current 
retention period is retained. If this parameter is present 
without a value, the retention period is set to the 
installation-defined value. 

R-vd New read permission control word to be applied to the 

existing permanent dataset. If this parameter is omitted, 
the existing read permission is retained. If R is present 
without a value, read permission is established as binary 
zeros. 

Vl=wt New write permission control word to be applied to the 

existing permanent dataset. If this parameter is omitted, 
the existing write permission is retained. If W is present 
without a value, write permission is established as binary 
zeros. 
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M=mn New maintenance permission control word to be applied to the 

existing permanent dataset. If this parameter is omitted, 
the existing maintenance permission is retained. If M is 
present without a value, maintenance permission is 
established as binary zeros. 



NA 



EX0(=0N 
I OFF 



No abort. If this parameter is omitted, an error causes the 
job to abort. 

Execute-only dataset. This parameter sets or clears 
the execute-only status of a dataset. EXO only or 
EXO=ON causes the dataset to be modified to execute-only. 
EXO=OFF causes the dataset to be modified to a 
non-execute-only dataset. If this parameter is omitted, the 
execute-only status of a dataset is unchanged. 



NOTE 

When processing for the MODIFY request is 
complete, all forms of examination of this 
dataset are prohibited if EXO=ON. 



DEIiETE - DELETE PERMANENT DATASET 

The DELETE control statement removes a mass storage permanent dataset from 
the Dataset Catalog (DSC) . To issue a DELETE of a dataset, the job must 
have previously accessed the dataset with maintenance permission, if 
specified on the SAVE control statement, and unique access (UQ) . The 
dataset remains a local dataset after DELETE until job termination. 
DELETE is a system verb. 

Format : 



DELETE, DN=dn,NA. 



Parameters: 
DN=dn 

NA 



Local dataset name of a permanent dataset accessed with 
maintenance permission and unique access 

No abort. If this parameter is omitted, a fatal error 
causes the job to abort. 



SR-0011 



Part 2 
4-11 



J-01 



DATASET STAGING CONTROL 



Two control statements support staging datasets between the CRAY-1 and a 
front-end system: ACQUIRE and DISPOSE. Another control statement, 
SUBMIT, directs datasets to the CRAY input queue. 

• ACQUIRE obtains a front-end resident dataset, stages it to the 
CRAY-1, and makes it permanent and accessible to the job making 
the request. Alternatively, if the dataset is already permanent 
on CRAY-1 mass storage, ACQUIRE allows dataset access to the job 
making the request. 

• DISPOSE directs a dataset to the specified queue for staging to a 
front-end system. DISPOSE can also be used to release a local 
dataset or to change dataset disposition characteristics. 

• SUBMIT directs a dataset on CRAY-1 mass storage local to the 
submitting job to the CRAY-1 input queue. 

Dataset control information such as save or access codes (required by a 
front-end system for management of its own files) can be sent by the 
CRAY-1 user to the front-end system through the use of TEXT, a special 
parameter of the ACQUIRE and DISPOSE statements. The contents of the 
character string provided with the TEXT parameter are defined by the 
front-end system. 

ACQUIRE and DISPOSE are invalid with tape datasets because these two 
statements apply only to the staging of datasets between a front-end 
computer system and the Cray computer. No interface exists between the 
Station Call Processor (SCP) and the Tape Queue Manager (TQM) . The tape 
subsystem is online to the CRAY-1 computer. 



ACQUIRE - ACQUIRE PERMANENT DATASET 

The ACQUIRE control statement allows the user to make a dataset permanent 
and accessible to the job making the request. ACQUIRE is a system verb. 

When an ACQUIRE control statement is issued, COS determines if the 
requested dataset is front-end resident or permanently resident on CRAY-1 
mass storage. 
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If the CRAY-1 Operating System determines that the requested dataset is 
already permanently resident on CRAY-1 mass storage, dataset access is 
granted to the job making the request. 

If the requested dataset is not a CRAY-1 permanent dataset, the request 
for the dataset is sent to the front-end system. The front-end system 
stages the dataset to the CRAY-1. COS then makes the dataset permanent 
and grants dataset access to the job making the request. Until the 
dataset is made permanent, processing of the job making the request is 
delayed. 



Format : 



ACQUIRE, DN=cin,PDN=pdw,iD=wid,ED=ed,RT=7»t;,R=r»d,w=wt,M=mn, 



\jQ,TEX'F=text,MF=mf, TiD=Hd,iiF=df, 



Parameters are in keyword form; the only required parameter is DN. 

DN=dn Local dataset name by which the permanent dataset is to be 
known. 1-7 alphanumeric characters, the first of which is 
A-Z, $, @, or %; remaining characters may also be numeric. 
DN is a required parameter. 

PDN=p(in Name of COS permanent dataset to be accessed or staged 

from a front-end system, saved, and accessed. This is the 
name that is saved by the system if the dataset is staged. 
pdn is 1-15 alphanumeric characters assigned by the 
dataset creator. The default for pdn is dn. 

TD-u'id User identification. 1-8 alphanumeric characters assigned 
by the dataset creator. The default is no user ID. 

ED-ed Edition number. A value from 1 through 4095 assigned by 

the dataset creator. The default value is: 

• One, if a permanent dataset with the same PDN and ID 
does not currently exist, or 

• The current highest edition number of that dataset 
if the permanent dataset with the specified PDN and 
ID does exist. 
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RT=rt Retention period. User-defined value from 0-4095 

specifying the number of days that a permanent dataset is 
to be retained by the system. The default value is an 
installation-defined parameter. 

R=rd Read control word. 1-8 alphanumeric characters assigned by 

the dataset creator. The default is no read control word. 

Vl=wt Write control word. 1-8 alphanumeric characters assigned 

by the dataset creator. The default is no write control 
word. 

M=mn Maintenance control word. 1-8 alphanumeric characters 

assigned by the dataset creator. The control word must be 
specified if a subsequent edition of the permanent dataset 
is saved. If no staging occurs, and the dataset is to be 
subsequently deleted, this parameter may be specified in 
conjunction with the UQ parameter (that is, maintenance 
permission is required to delete a dataset) . 

UQ Unique access. If specified, the job is granted unique 

access to the permanent dataset; otherwise, multiaccess to 
the permanent dataset is granted. If no staging is 
performed because the dataset already exists, write, 
maintenance, and/or read permission may be granted if the 
appropriate write or maintenance control words are 
specified. 

TEXT=text 

Text to be passed to the front-end system requesting 
transfer of the dataset. The format for TEXT is defined by 
the front-end system for managing its own datasets or 
files. Typically, text is in the form of one or more 
control statements for the front-end system; these 
statements must contain their own terminator for the front 
end. Any COS record control words are extracted from the 
text string before it is passed to the front end. text 
cannot exceed 240 characters. 

MF=m/ Mainframe identifier for the front-end computer. Two 

alphanumeric characters. The default is the mainframe of 
job origin. 

TlD=t'Cd Terminal identifier. 1-8 alphanumeric characters 

identifying destination terminal. The default is terminal 
of job origin. 

DF=d/ Dataset format. This parameter defines whether a dataset 
is to be presented to the CRAY-l in COS blocked format and 
whether the front-end system is to perform character 
conversion. The default is CB. 
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For example, a user may wish to acquire a dataset from 
magnetic tape in blocked binary as it appears at the 
front-end system. In this case, BB is specified. 

<:^ is a 2-character alpha code defined for use on the 
front-end system. The default is CB. Cray Research 
suggests support of the following codes: 

CD Character deblocked. The front-end system performs 
character conversion to 8-bit ASCII, if necessary. 

CB Character blocked. The front-end system blocks the 
dataset prior to staging and performs character 
conversion to 8-bit ASCII, if necessary. 

BD Binary deblocked. The front-end system does not 

perform character conversion. For ACQUIRE, BD is the 
same as TR. 

BB Binary blocked. The front-end system blocks the 
dataset prior to staging but does not do character 
conversion, 

TR Transparent. No blocking/deblocking or character 
conversion is performed. 



DISPOSE - DISPOSE DATASET 

The DISPOSE control statement directs a dataset to the CRAY-1 output 
queue for staging to a specified front-end computer system (mainframe) . 
DISPOSE can also be used to alter dataset disposition characteristics or 
to release a dataset. 

Defining the DISPOSE characteristics can be done before the actual 
staging via the DEFER parameter. The DEFER parameter saves all selected 
dispose parameters for use when the dataset is released, which is when 
the actual staging is initiated. DISPOSE is a system verb. 
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Format: 



D ISPOSE , DN=dn , SDN=edn , DC=dc , DF=d!/,MF=w/, SF=e/, ID=Mid, TlD=Hd, 



ED=ed, RT=rt , R=rd,V!=wt , M=nm,TEX'r=text , wait ,nowait , defer ,nrls . 



Parameters are in keyword form; the only required parameter is DN. 

DN=(in Local dataset name. Name by which the dataset is known at 
the CRAY-1, DN is a required parameter. 

SDH=sdn Staged dataset name. 1-15 character name by which the 
dataset will be known at destination mainframe. The 
default for edn is dn. 

DC=dG Disposition code. Disposition to be made of the dataset. 

The default is PR when the DC parameter is omitted. 

do is a 2-character alpha code describing the destination 
of the dataset as follows: 

IN Input (job) dataset. Dataset is queued as a job on 
the mainframe specified with the MF parameter. 

ST Stage to mainframe. Dataset is made permanent at the 
mainframe designated by the MF parameter. 

SC Scratch dataset. Dataset is released. 

PR Print dataset. Dataset is printed on a printer 
available at the mainframe designated by the MF 
parameter . 

PU Punch dataset. Dataset is punched on any card punch 
available at the mainframe designated by the MF 
parameter . 

PT Plot dataset. Dataset is plotted on any available 
plotter at the mainframe designated by the MF 
parameter . 
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MT Write dataset on magnetic tape at the mainframe 
designated by the MF parameter. 

T^F=df Dataset format. This parameter defines whether a dataset 

is sent from the CRAY-1 in COS blocked format and whether 
the front-end system is to perform character conversion. 
The default is CB. 

For example, a user may wish to save a dataset on magnetic 
tape in blocked binary as it appears at the CRAY-1. In 
this case, BB is specified. A user who wants a dataset 
printed will specify CB if the front-end computer handles 
deblocking. 

d^f is a 2-character alpha code defined for use on the 
front-end system. Cray Research suggests support of the 
following codes: 

CD Character deblocked. The front-end system performs 
character conversion from 8-bit ASCII, if necessary. 

CB Character blocked. No deblocking is performed at the 
CRAY-1 prior to staging. The front-end system 
performs character conversion from 8-bit ASCII, if 
necessary. 

BD Binary deblocked. The front-end system does not 
perform character conversion. 

BB Binary blocked. The front-end system does not 

perform character conversion. The CRAY-1 does not 
perform deblocking prior to staging. For DISPOSE, BB 
is the same as TR. 

TR Transparent. No blocking/deblocking or character 
conversion is performed. 

Other codes may be added by the local site. Undefined 
pairs of characters may be passed but will be treated as 
transparent mode by the CRAY-1. 

VIF~mf Mainframe computer identifier. Two alphanumeric 

characters. Identifies the front-end station where the 
dataset is to be staged. If omitted, the mainframe where 
the issuing job originated is used. If MF is given a value 
of a CRAY-1 ID and DC=IN, the dataset is disposed to the 
CRAY-1 input queue after issuing a warning message (see 
note) . 
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NOTE 

In future versions of COS, the SUBMIT control statement 
will be the only way to place datasets into the CRAY-1 
job input queue. Therefore, it is advisable to use 
SUBMIT instead of DISPOSE to dispose datasets to the 
CRAY-1 input queue. If DISPOSE is used to submit a job 
to the CRAY-1 input queue, the following informative 
message is printed in the logfile: SY004 - USE SUBMIT 
TO PLACE JOBS IN CRAY INPUT QUEUE. 



SF-sf Special form information to be passed to the front-end 

system. 1-8 alphanumeric characters. SF is defined by the 
needs of the front-end system. 

ID-uid User identification. 1-8 alphanumeric characters assigned 
by the dataset creator. The default is no user ID. 

TlD^tid Terminal identifier. 1-8 alphanumeric characters 

identifying destination terminal. The default is terminal 
of job origin, where applicable. 

ED=ed Edition number, meaningful only if DC=ST. A user-defined 

value from 1 through 4095. The default value depends on 
the destination mainframe. 

RT=r»t Retention period, meaningful only if DC=ST. A user-defined 
value from through 4095 specifying the number of days a 
dataset is to be retained by the destination mainframe. 
The default value depends on the destination mainframe. 

R=rd Read control word, meaningful only if DC=ST. 1-8 

alphanumeric characters. The default is no read control 
word. 

V!=Wt Write control word, meaningful only if DC=ST. 1-8 

alphanumeric characters. The default is no write control 
word. 

M=mn Maintenance control word, meaningful only if DC=ST. 1-8 

alphanumeric characters. The default is no maintenance 
control word. 
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TEXi=text 



Text to be passed to the front-end system requesting 
transfer of a dataset. The format for TEXT is defined by 
the front-end system for managing its own datasets or 
files. Typically, text is in the form of one or more 
control statements for the front-end system; these 
statements must contain their own terminator for the front 
end. Any COS record control words are extracted from the 
text string before it is passed to the front end. text 
cannot exceed 240 characters. 

WAIT Job wait. When this parameter is specified, the job does 
not resume processing until the disposed dataset has been 
staged to the front-end system. If the front-end system 
cancels the transfer, the waiting job is aborted. 
Processing then resumes after the next EXIT statement, if 
one is present. If WAIT is not specified, processing 
resumes immediately upon issue of the DISPOSE, depending 
upon an installation option. The WAIT parameter is useful 
in detecting unsuccessful transfers. 

NOWAIT Job no wait. When this parameter is specified, the job 
will not wait until the dataset has been staged to the 
front-end system but resumes processing immediately. If 
the front-end system cancels the transfer, no special 
action is taken, that is, the job is not aborted. If 
NOWAIT is not specified, processing resumes immediately 
upon issue of the DISPOSE, depending upon an installation 
option. 

DEFER When this parameter is specified, the disposition occurs 

when the dataset is released either by a RELEASE request or 
job termination. The dispose characteristics are saved and 
used when the dataset is released. 

NRLS No release. When this parameter is specified, the dataset 
remains local to the job after the DISPOSE request has been 
processed. When NRLS is specified on a DISPOSE control 
statement, the dataset cannot be written to, until the 
transfer to the specified front-end is completed. 
Therefore, it is advisable to use WAIT with NRLS. 
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SUBMIT - SUBMIT JOB DATASET 

With SUBMIT, a job running on the CRAY-1 can direct another dataset 
(which must also be a job) to the CRAY-1 input queue. The job that is 
submitted executes independently of the submitting job, SUBMIT is a 
system verb. 



Format: 



SUBMIT , DN=dn , S ID=;7?f , DID=ff^ , TID=t;id , DEFER , NRLS . 



Parameters are in keyword format; the only required parameter is DN, 



DN=dn 



SID=7^f 



DlD=mf 



TiD=tid 



DEFER 



Local dataset name. A valid local dataset name, 
required parameter and must be given a value. 



DN is a 



Default source front-end system identifier. Two 
alphanumeric characters. If an MF parameter is not 
specified in an ACQUIRE control statement for the submitted 
job, the SID parameter defines the default source front-end 
system for the dataset to be acquired. If the MF parameter 
as well as the SID are omitted, the default source 
identifier of the submitting job is used. 

Default destination mainframe identifier. Two alphanumeric 
characters. If an MF parameter is not specified in a 
DISPOSE control statement for the submitted job, the DID 
parameter defines the default destination front-end system 
for the dataset to be acquired. If the MF parameter as 
well as the DID are omitted, the default destination 
identifier of the submitting job is used. 

Default terminal identifier. 1-8 alphanumeric character 
identifier which defines the default terminal ID for the 
submitted job. If omitted, then the terminal ID of the 
submitting job is used. 

Deferred submit. Selection of this parameter causes the 
SUBMIT characteristics to be defined, with a release of the 
dataset actually initiating the submit of the dataset. If 
omitted, the SUBMIT occurs immediately. 
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NRLS No release. This parameter indicates if the dataset is to 
remain local to the job after SUBMIT has been processed. 
If omitted, the dataset is released after the SUBMIT. If 
selected, the dataset remains local to the job after the 
SUBMIT. If the dataset is not released, it is available 
for reading only. When NRLS is specified on a SUBMIT 
control statement, the dataset cannot be written to, until 
the transfer to the specified front-end is completed. 
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DATASET UTILITIES 



Utility control statements provide the user with a convenient means of 
copying, positioning, or dumping datasets. The following utilities 
are available to the user: 

• COPYR, COPYF, and COPYD allow the user to copy records, files, 
or datasets, respectively. 

• SKIPR, SKIPF, and SKIPD allow the user to skip records, files, 
or datasets, respectively. 

• REWIND positions a dataset at the beginning of data, that is, 
prior to the first block control word of the dataset. 

• WRITEDS is intended for initializing a random dataset but may 
also initialize a sequential dataset. 

All parameters are in keyword form and have default values. 



COPYR - COPY RECORDS 

The COPYR statement copies a specified number of records from one 
dataset to another starting at the current dataset position. 
Following the copy, the datasets are positioned after the 
end-of-record for the last record copied. 



Format: 



COPYR, l=idn,0=odn,^R=n. 
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Parameters are in keyword form. 

l=idn Name of dataset to be copied. The default is $IN. 

0=odn Name of dataset to receive the copy. The default is 

$OUT. 

NR=rz Decimal number of records to copy. The default is 1. 

If the dataset contains fewer than n records, the copy 
prematurely terminates on the next end-of-file. 
End-of-file or end-of-data is not written. If the 
keyword NR is specified without a value, the copy 
terminates at the next end-of-file. If the input 
dataset is positioned midrecord, the partial record is 
counted as one record. 



COPYF - COPY FILES 

The COPYF statement copies a specified number of files from one 
dataset to another starting at the current dataset position. 
Following the copy, the datasets are positioned after the end-of-file 
for the last file copied. 



Format: 




Parameters are in keyword form. 

l=-idn Name of dataset to be copied. The default is $IN. 

O=odn Name of dataset to receive the copy. The default is 

$OUT. 

NF=n Decimal number of files to copy. The default is 1. If 

the dataset contains fewer than n files, the copy 
prematurely terminates on end-of-data. End-of-data is 
not written. If the keyword NF is specified without a 
value, the copy terminates at the end-of-data. If the 
input dataset is positioned midfile, the partial file 
counts as one file. 
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COPYD - COPY DATASET 

The COPYD statement copies one dataset to another starting at their 
current positions. Following the copy, both datasets are positioned 
after the end-of-file of the last file copied. The end-of-data is not 
written to the output dataset. Both input and output datasets must be 
blocked. 



Format : 



COPYD , iHdn , 0-odn . 



Parameters are in keyword form. 

I=^(in Name of dataset to be copied. The default is $IN. 

0-odn Name of dataset to receive the copy. The default is $OUT. 



SKIPR - SKIP RECORDS 

The SKIPR control statement directs the system to bypass a specified 
number of records from the current position of the named dataset. 



Format : 



SKIPR, DN=dn,NR=n. 



Parameters are in keyword form. 

DN=<in Name of dataset to be bypassed. The default is $IN. 

NR=n Decimal number of records to skip. The default is 1. If 
the keyword NR is specified without a value, the system 
positions dn after the last end-of-record of the current 
file. If n is negative, SKIPR skips backward on dn. 
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SKIPR does not bypass an end-of-f ile or beginning- 
of-data. If an end-of-file or beg inning-of -data is 
encountered before n records have been bypassed when 
skipping backward, the dataset is positioned after the 
end-of-file or beg inning-of -data; when skipping forward, 
the dataset is positioned after the last end-of-record of 
the current file. This statement is available for use with 
online tapes except that a negative value cannot be used 
for NR. 



SKIPF - SKIP FILES 

The SKIPF control statement directs the system to bypass a specified 
number of files from the current position of the named dataset. 



Format : 



SKIPF, DN=dw,NF=w. 



Parameters are in keyword form. 

DN=(in Name of dataset to be bypassed. The default is $IN. 

NF=n Decimal nuifnber of files to bypass. The default is 1. If 
the keyword NF is specified without a value, the system 
positions dn after the last end-of-file of the dataset. 
If n is negative, SKIPF skips backward on dn. 

If dn is positioned midfile, the partial file skipped 
counts as one file. 

SKIPF does not bypass an end-of-data or beg inning-of -data, 
If beginning-of-data is encountered before n files have 
been bypassed when skipping backward, the dataset is 
positioned after the beginning-of-data? when skipping 
forward, the dataset is positioned before the end-of-data 
of the current file. This statement is available for use 
with online tapes except that a negative value cannot be 
used for NF; for interchange format tapes (DF=IC) , NF can 
only be 1. 



Part 2 
SR-0011 6-4 J-01 



For example, if dn is positioned just after an 

end-of-f ile, the following control statement will position 

dn after the previous end-of~file. If dn is positioned 

midfile, dn will be positioned at the beginning of that 

file. 

SKIPF,DN=dn,NF=-l . 



SKIPD - SKIP DATASET 

The SKIPD control statement directs the system to position a dataset at 
end'-of-data , that is, after the last end-of-f ile of the dataset. It has 
the same effect as the following statement: 

SKIPF,DN=dn,NF. 

If the specified dataset is empty or already at end-of-data, the 
statement has no effect. 



Format: 



SKIPD, DN=dn. 



The parameter is in keyword form. 

DN=dn Name of dataset to be skipped. The default is SIN. 



REWIND - REWIND DATASET 

The REWIND control statement positions the named datasets at the 
beginning-of-data, that is, prior to the first block control word of the 
dataset. The $IN dataset represents an exception. After REWIND, $IN is 
positioned after the control statement file. If any of the named 
datasets is not open, REWIND opens it. REWIND is a system verb. 
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REWIND causes an end-of-data to be written to the dataset if the previous 
operation was a write or if the dataset is null. If the dataset is not 
memory resident, the buffers are flushed to mass storage when REWIND 
follows a write operation. If the dataset is memory resident, the 
end-of-data is still placed in the buffer, but the buffer is not 
flushed. For an online magnetic tape dataset, REWIND positions the tape 
dataset to the beginning of the first volume accessed by the user. 



Format : 



REWIND ,DN=dwi :(in2 : . . . idriQ . 



Parameters are in keyword form. 

Names of datasets 

datasets can be specified, separated by colons. 



DN=dn« Names of datasets to be rewound. A maximum of eight 



WRITEDS - WRITE RANDOM OR SEQUENTIAL DATASET 

The WRITEDS control statement is intended for initializing a blocked 
dataset. It writes a dataset containing a single file consisting of a 
specified number of records of a specified length. This utility is 
especially useful for random datasets because a record written on a 
random dataset must end on a pre-existing record boundary. Direct-access 
datasets, implemented in CFT as defined by the ANSI x3. 9-1978 FORTRAN 
standard, can be initialized (and even extended) without the help of 
WRITEDS. 

WRITEDS can also be used to write a sequential dataset. 



Format : 



WRITEDS , DN=dn , NR=nr' , I(L=rl . 



Parameters are in keyword form; the only required parameters are DN and 
NR. 

DN=(in Name of dataset to be written. DN is a required parameter. 
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NR=nr' Decimal number of records to be written. NR is a required 
parameter. Set to the largest value that may be needed, 
since a dataset cannot be extended when it is in random 
(RDM) mode. 

RL=rl Decimal record length, that is, the number of words in each 

record. The default is zero words, which generates a null 
record. 

If the record length is 1 or greater, the first word of 
each record is the record number as a binary integer 
starting with 1. 
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PERMANENT DATASET UTILITIES 



The following utility routines are provided for permanent datasets: 

• PDSDUMP dumps all specified permanent datasets to a 
user-specified dataset. Input and output datasets may be 
included in the dump. 

• PDSLOAD loads permanent datasets that have been dumped by 
PDSDUMP and updates or regenerates the Dataset Catalog. Input 
and output datasets are also loaded via PDSLOAD. 

• AUDIT produces a report containing status information for each 
permanent dataset. AUDIT does not include input or output 
datasets. 



PDSDUMP - DUMP PERMANENT DATASET 

PDSDUMP dumps specified permanent datasets to a dataset, which may 
then be saved or staged to a station as desired. Conditions that 
cause a dataset to be omitted from dumping include: 

• The dataset is execute-only, 

• There are dataset allocation conflicts, 

• The dataset has catastrophic errors, 

• Inconsistent allocation has occurred, 

• The dataset resides on a down device, or 

• The dataset has an inactive entry in the system's Queued 
Dataset Table (QDT) . 



Format : 



PDSDUMP , DN=dn , DV=ldV , PDS=pcf 8 ,CVI=eW , 



lD=wi(i,US=wsn,ED=e(i,X,C,D,l,0,S, 
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All parameters are in keyword form. Optional parameters establish 
criteria for datasets being dumped. 

DN=(in Name of dataset where dump is written. The default is 
$PDS. Multiple dumps to a dataset are possible; if the 
dataset specified already exists r the dump is appended to 
it. 

D'V=ldv Dump all datasets residing on logical device Idv, 
Currently only one Idv can be specified.^ 

TPDS^ds Dump all editions of the specified permanent dataset. 
Editions may be limited by ED parameter.^ 

CV}=ow Installation-defined control word regulating use of 

PDSDUMP. If the user number is specified on the JOB 
control statement, the CW parameter is not usually 
required; only the datasets with that user number are 
selected. If the CW parameter is omitted, only the 
datasets belonging to the user number as specified on the 
JOB control statement can be dumped. If the CW parameter 
is present and the correct control word is used, any 
dataset can be dumped. If an invalid control word is 
given, the job is aborted, when the user number is omitted 
from the JOB control statement, CW is a required parameter. 

ID=wi(i Dump all datasets with user identification as specified.^ 

If ID is specified without a value, all datasets which meet 
the rest of the criteria and have a null id are dumped. 

\JS=usn Dump all datasets with specified user number.^ 

ED=ed Edition number of permanent dataset dumped; meaningful only 

if PDS parameter is specified.^ 

X Dump expired datasets. 

C Dump selected datasets never dumped or datasets modified 
since the last dump of the dataset. 

D Delete datasets that are dumped. 

I Dump system input datasets. 

O Dump system output datasets. / See note 

S Dump user permanent datasets. 



By default, all permanent datasets specified by the parameters are 

fiDP>d . 



dumped 
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NOTE 



If none of these parameters is specified, the input, 
output, and user permanent datasets are all dumped. 
If any of these parameters is specified, only those 
datasets of the type specified are dumped. 



Multiple calls to PDSDUMP may be made if the dump dataset is to include 
several permanent datasets requiring specification of different 
parameters. 

Example: 

PDSDUMP , DN=DUMPA , PDS=LIB1 . 
PDSDUMP, DN=DUMPA,PDS=LIB2 . 

This example results in a dataset DUMPA that contains all editions of 
LIBl and all editions of LIB2. 

PDSDUMP produces a listing (figure 7-1) on $OUT identifying the datasets 
dumped or bypassed and summarizing the dump run. The date and time in 
the heading line refer to the time when the dump run started. The 
permanent dataset name, edition number, ID, and user number are extracted 
from the DSC entry for each dataset selected. Each message is followed 
by the notation DUMPED or NOT DUMPED. The notation NOT DUMPED indicates 
the dataset was selected but could not be accessed for dumping. A user 
logfile message further explains the problem encountered. 

When dumping to a tape dataset, the recording format for the tape dataset 
must be transparent (for example, DF=TR on ACCESS statement). If the 
dataset is recorded in interchange format loading, using the dump dataset 
leads to unsuccessful results. 
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PDSDUMP - PERMANENT DATASET DUMP UTILITY DUMP ON 



AUDPL 

AUDPL 

DSCED 

DSCED 

TXBUILD 

TXBUILD 

TXBUILD 

LONGDATASETNAME 

LONGDATASETNAME 

LONGDATASETNAME 

LONGDATASETNAME 

DSBUILD 

DSBUILD 

DSBUILD 

DSBUILD 

AUDPL 

DSCED 

TXBUILD 

AUDPL 

DSCED 

20 



01/07/82 AT 

ED=0001 ID^QITTYQAT USR=SYSTEM DUMPED 

ED=0002 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0001 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0002 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0001 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0002 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0003 ID*QITTYQAT USR=SYSTEM DUMPED 

ED=0001 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0002 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0003 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0004 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0001 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0002 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0003 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0004 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0003 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0003 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0004 ID=QITTYQAT USR=SYSTEM DUMPED 

ED=0004 ID=QITTYQAT USR=SySTEM DUMPED 

ED=0004 ID=QITTYQAT USR=SYSTEM DUMPED 
DATASETS SELECTED FOR DUMPING 



14:50:44 



Figure 7-1. PDSDUMP listing 



PDSLOAD *• LOAD PERMANENT DATASET 

PDSLOAD loads permanent datasets from a dataset created by PDSDUMP. If 
the dataset already exists, it is not reloaded. 



Format: 



PDSLOAD,DN=(in,PDS=pds,CW=cW, ID=wid,US=MSw,ED=ed,DV=dz;n,A, 1 ,0,S ,NA. 



All parameters are in keyword form. Optional parameters establish 
criteria for datasets being loaded. 

DN=dn Name of dataset from which permanent dataset is to be 
loaded. The default is $PDS. 

PDS^pde Load all editions of the specified permanent dataset. 
Editions may be limited by the ED parameter.^ 



§ By default, all permanent datasets that are specified by the 
parameters are loaded. 
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CW=cW Installation-defined control word to regulate the use of 

PDSLOAD. The GW parameter is usually not required. If the 
CW parameter is used when the user number is specified, the 
datasets with the user number are searched. If the CW 
parameter is omitted when the user number is specified, 
only the datasets belonging to that user number may be 
loaded . 

When the user number is omitted from the JOB control 
statement, CW is a required parameter. When the CW 
parameter is specified on the PDSLOAD control statement, 
the user can load any datasets with the correct control 
word. If an invalid control word is given, the job is 
aborted. 

lD=ui,d Load all datasets with user identification as specified. 

US=Msw Load all datasets with specified user number.^ 

ED=ed Edition number of dataset to be loaded; meaningful only if 

PDS parameter is specified.^ 

DV=dvn The name of a logical device where the output dataset is 
assigned before it is opened. If omitted, COS assigns a 
device at open time. If specified, the supplied device 
name is built into the DNT entry for the output dataset 
(the one being loaded) . Note that COS can choose not to 
honor this assignment. This parameter is not involved in 
any way in the selection of a dataset for loading. 

A Load only active datasets; that is, do not load expired 
datasets. 



I 

S 
NA 



Load input datasets. 
Load output datasets. 
Load saved datasets. 



See note following 



Do not abort if there is not a dataset matching the 
specifications to load on the $PDS dataset. This parameter 
applies only to this situation. It does not prevent any 
other abort condition from occurring or offer reprieve 
processing of any kind. 



By default, all permanent datasets that are specified by the parameters 
are loaded. 
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NOTE 

If none of these parameters is specified, the 
input, output, and saved datasets are loaded. 
If any of these parameters is specified, only 
those datasets of the type specified are loaded, 



PDSLOAD produces a listing on $OUT identifying the datasets loaded or 
bypassed and summarizing the load run. The date and time in the heading 
line refer to the time when the load run started. The permanent dataset 
name, edition number, ID, and user number are extracted from the PDD for 
each dataset selected and successfully loaded. Each message is followed 
by the notation LOADED or NOT LOADED. The notation NOT LOADED indicates 
the dataset was selected but not loaded. A user logfile message further 
explains the problem encountered. 



PDSLOAD - PERMANENT DATASET RESTORE UTILITY LOAD ON 01/07/82 AT 17:13:47 
ENTIT ED=0001 ID=TAQI 

DSBUILD ED=0001 ID=TAQI 
TXBUILD ED=0001 ID=TAQI 
AUDPL ED=0001 ID=TAQI 

DSCED ED=0001 ID=TAQI 

5 DATASETS SELECTED FOR LOADING 



USR=SySTEM 


LOADED 


USR=SYSTEM 


LOADED 


USR=SYSTEM 


LOADED 


USR=SYSTEM 


LOADED 


USR=SYSTEM 


LOADED 



AUDIT - AUDIT PERMANENT DATASETS 

The AUDIT utility provides reports on the status of each permanent dataset 
known to the system. If the user number for the job is SYSTEM, AUDIT reports 
on all permanent datasets. Otherwise, AUDIT only reports on those permanent 
datasets whose user number matches the user number for the job. AUDIT does 
not include input and output datasets. 

If more than one parameter is selected, only those datasets which meet all 
criteria are listed. Parameter values can be selected that conflict with each 
other, such as PDN and PREFIX. For example, requesting that permanent dataset 
names that begin with ABC (PDN=ABC-) and whose prefix characters are BOT 
(PREFIX=BOT) would result in no permanent datasets being listed. 

AUDIT supplies the following information on the listing: 



I 



Permanent dataset name 
Edition number 
User identifications 
Dataset size in words 
Retention time in decimal 
Number of accesses in decimal 
Total block count in decimal 



Creation date/time 

Last dump date/time 

Last access date/time 

Last modification date/time 

Logical device name 

Number of datasets selected 
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Format: 



AUDIT, L=Jdn ,B=Z?dn,PDN=pdn, lD=wid,PREFix=p/a;,DV=dyn, 



S Z=d63 , X^mm/dd/yy i^hhzmrmss* , TCR=mm/dd/yy i^hhtmm:ss\ 



TLh^rm/dd/yyi^hhimrmee* ,TiM=mm/dd/yy'.*hhimmi8s' 



Parameters are in keyword form. 

L=ldn List dataset name. The default is $OUT. 

B=bdn Specifies dataset to receive the binary output. If B is 

specified alone, the dataset is $BINAUD. If the B parameter 
is omitted, no binary output is written. For a description 
of the binary output format, refer to the COS Product Set 
Internal Reference Manual, CRI publication SM-0041. 

PDN=p(in Name of permanent dataset or datasets to be listed. Up to 
15 alphanumeric characters may be specified. A shorthand 
notation may be used where a dash represents any number of 
characters or no characters and an asterisk represents any 
one character. 

Examples ; 

PDN=ABC- List all permanent dataset names beginning 
with ABC. 

PDN=A*** List all 4-character permanent dataset names 
beginning with A. 

PDN=-A*- List all permanent dataset names containing 
the letter A followed by one or more other 
characters. 

PDN=- List all names. 

PDN=***- List all names having three or more 
characters. 
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ID^uid List all permanent datasets with the specified user 

identification. The default is to list all IDs. If ID is 
present without an equated value r datasets having a null id 
are selected. 

PREFIX=p/a; 

List all permanent datasets whose names begin with the 
specified prefix, pfx is 1-8 characters. The default is 
no prefix specified. 

DV=dvn List all permanent datasets on the specified logical 

device. The default is to list permanent datasts on all 
devices. 

SZ=dss List all permanent datasets greater than or equal to the 

specified size. Size is specified in words. The default is 
to list all sizes. 

X=mm/dd/yyi ^hhzmrmss^ 

List all permanent datasets that are expired as of the 
specified mm/dd/yyz^hhzmmi s 8* . rnm/dd/yy 
may be specified alone. The default expiration date and 
time are "now" if only X is specified. 

TCR=mm/dd/yyi*hhtmmiSs'' 

List all permanent datasets that have been created since the 

specified mm/dd/yyi*hh:mm',S6* * The keyword 

cannot be specified alone; however, TCR-mrn/dd/yy is 

sufficient. 

TLh=mm/dd/yy :*hhimm:6S* 

List all permanent datasets that have not been accessed 
since the specified mm/dd/yyi*hhimm:ss^ . The 
keyword cannot be specified alone; however, 
TLk-mm/dd/yy is sufficient. 

TlM=mm/dd/yy : ' hh zmm : es ' 

List all permanent datasets that have been modified since 
the specified rnm/dd/yyx^hhimmiss* . The keyword 
cannot be specified alone; however, TIM=mm/dd/yy is 
sufficient. 
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ANALYTICAL AIDS 8 



The following control statements provide analytical aids to the 
programmer: 

• DUMPJOB and DUMP are generally used together to examine the 
contents of registers and memory as they were at a specific time 
during job processing. DUMPJOB captures the information so that 
DUMP can later format selected parts of it. 

• DEBUG produces a symbolic dump. 

• DSDUMP dumps all or part of a dataset to another dataset in one of 
two formats: blocked or unblocked. 

• COMPARE compares two nearly identical datasets and lists all 
differences. 

• FLODUMP dumps flowtrace tables when a program aborts with 
flowtrace active. 

• PRINT writes the value of an expression to the logfile. 

• SYSREF generates a global cross-reference listing for a group of 
CAL or APML programs. 



DUMPJOB - CREATE $DUMP 

The DUMPJOB control statement causes creation of the local dataset $DUMP, 
if not already existent. $DUMP receives an image of the memory assigned 
to the job (JTA and user field) when the DUMPJOB statement is 
encountered. If DUMPJOB is placed after a system verb (excluding the 
comment and EXIT statements) , the dump is of the Control Statement 
Processor (CSP) . A DUMPJOB statement is not honored if an execute-only 
dataset is loaded in memory; a DUMPJOB to an execute-only dataset is 
rejected. 

If $DUMP already exists, it is overwritten each time a DUMPJOB control 
statement is processed. If $DUMP is permanent and the job does not have 
write permission, DUMPJOB aborts. If $DUMP is permanent and the job has 
write permission, the dataset is overwritten. 
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If the DUMPJOB/DUMP sequence fails because of such situations as 
destroyed system-managed DSPs, assign $DUMP and save it with unique 
access. DUMPJOB writes to $DUMP, and job termination automatically 
adjusts $DUMP. $DUMP can then be inspected in a separate job. 

$DUMP is created as an unblocked dataset by DUMPJOB for use by DUMP. 
DUMPJOB is a system verb and cannot be continued to subsequent cards 



Format: 



DUMPJOB. 



Parameters: none 



DUMP - DUMP REGISTERS AND MEMORY 

DUMP reads and formats selected parts of the memory image contained in 
dDUMP and writes the information onto another dataset. The DUMP 
statement can be placed anywhere in the control statement file after 
^DUMP has been created by the DUMPJOB control statement. 

Placing the DUMPJOB and DUMP statements after an EXIT statement is 
conventional and provides the advantage of giving the dump regardless of 
which part of the job causes an error exit. The usage of DUMP and 
DUMPJOB, however, is not restricted to this purpose. 

DUMP can be called any number of times within a job. This might be done 
to dump selected portions of memory from a single $DUMP dataset or it 
might be done if $DUMP has been created more than once in a single job. 



Format : 



DUMP , I=idn ,0=odn,FW=/Wa,LW=Zwa ,JTA,NXP ,V, DSP ,FORMAT=/,CENTER. 



Parameters are in keyword form. 

l=idn Name of the dataset containing the memory image. The 

dataset $DUMP is created by DUMPJOB and is the default, but 
any dataset in the $DUMP (unblocked) format is acceptable. 

0=<3(in Name of the dataset to receive the dump; default is $OUT. 
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¥Vl-fwa Octal first word address of memory to dump. The default 
is 0. 

l}/i=twa Octal last word address+1 of memory to dump. The 

default is 2003. Specifying the keyword LW without a 
value causes the limit address to be used, 

JTA Job Table Area to be dumped. The default is no dump. 

NXP No exchange package, B registers, or T registers 
dumped. The default causes exchange package, B 
registers, and T registers to be dumped. 

V Vector registers to be dumped. The default is no dump 
of V registers. 

DSP Logical File Tables (LFTs) and Dataset Parameter Areas (DSPs) 
to be dumped. The default is to not dump LFTs and DSPs. 

FORMAT=/ Format for the part of memory selected by FW and LW. 
The options are: 

Octal integer and ASCII character. This is 
the default. 

D Decimal integer and ASCII character 

X Hexadecimal integer and ASCII character 

G Floating point or exponential (depending on 
the value of the number) and ASCII character 

P 16-bit parcel (4-word boundaries are forced 
for FW and LW) 

M Mixed hexadecimal and octal written in ASCII. 
Each 16-bit parcel is represented as five 
characters; the first is a hexadecimal digit 
representing the upper 4 bits and the next 
four are octal characters representing the 
lower 12 bits. 

CENTER Dump IOO3 words on each side of the address contained 
in the P register of the exchange package. The format 
is P. 
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Examples; 

The following example is a portion of the dump obtained using format 
0, the default format type: 



UStFR FIELD (FOf?MATrO) 



DUMP X.ia7 79254 09/11/79 



0000100 0451172043047114632400 

0W0104 O0O0P0000000k'000000C00 
O.J.Wl 10 0000000000000000000000 

f>.')r4 eiiO0O00O0O00OO00iX,'O000 

O'r.'<'i;'o (■•«)< '00oo00O0OWi00O('<0COo 

00'>0t;'4 0<iO0tW000O000O00O0<2i0l» 

00>X);.'00 04;'i?Br::j2S00402i4<475<'-:? 

001W,':T'4 0904 ■'0164:??0:'1 1643t4«; 
0000^:10 0(.?3Mr,?14f;314rj314f;314S 

0000c? 1 4 04 00000000 1 1 0020000203 

*i* l-.ND OF D,iMP *** 



0000000000022000137000 0000040011700000116600 0000070000000000116562 wCBlS^S 

l(d<?<2r0000O0O00O000(?<D00<3 00O00i30<?ti00OO0OO00(?0O0 00000000(50000000000000 

oooooooooeooo'X'iooooooi? 00000^000000000000000 0000000000000000000000 



O^/'ll-'TPir 4?. 35 



0OO00O000OO0OO0000Oi?0O 030071 i:ic;3046113e33471 O:J047O1<5.1 32071 164 314G5 

0O00OOff'Oi*x>O'''Oi?0(io(>x^ ixx>vof:i(Hxxxx'Oi.">oo«W00O oooooooi?ii"^oo'Xioo>"n?i(Viooo 

0;i007n'*33C4f>li:K:CM;.'l 030'tVOlM3?0^11G4314CE «?0tH3O0<X'0OOOOO0OO<»X> 09/ll/7yiS 4? 35 

04n5Ol;:'iO2Ol?^irS250lP'. O5140OO<-»OO>?O00tiOO0fKX>0 030(?i7113e30<)61 13^33471 IX»>P FORtlAT TYPE" 09/U.'7g 

00OlXlO0c>?O000tXi(:)0OO(X^O 17V777A';'777777777-'777 1234'3G701234!X5701234M 18 4935 

01O44,-:O'HV?i,7<.,,;'f3O(H?'.. 140i>. 7iv .43'.;43243211234 03771 24 W(>0O00O<:X?O0OOO " 7 ■ ? 

OO400(X-!0O0O00OOvi64O100 OO<\'O4O,'O0O100OtWi?iv>>O0 004000220445 102,?2441 11 f t(» I? W • HIHIMI 



A portion of the dump in format D: 



USFR FIFI.D CF0RMf^T=D5 



DUMP X.07 79254 09/11/79 



0000100 


5354571261147297024 


0000104 





0000110 







ttttt 


0000164 





0000170 





0000174 





OOOOJ-'OO 


4<?23326774 1 3370G578 


p',v:^,->04 


3546648702527091509 


ev;io.';t0 


7:3:'8637629483320G45 


00'3ori.<i 


4611 G86028095,=5y 755 




*>:* KNU OF DUMP *** 



24153*57744 
--9223372036SS4 7 '>.«08 




34748604 75S-!I.8129rO'.i 
55G(:.8231 J .7.r'374e'c''7f/;^ 

O 
1 2345678901 r:345G7S0 
5'f^531 1210478 1 420r^ 



1126578511715712 




347.18^0475818129209 



3'o46n487O2S,?709t509 

5^180 -'80305 1 480 1 8688 

-1 

- 4595;-i69345371 434340 

3^1(>3'1940'.ii.57iv;24 



197032483>l?'14898 J0B1935 




09/11/7918 49 35 



09/11/7918 49 35 



3546648702527091509 



34748<r,O't75818l29209 DU1P FOR-V^T TNPES 09/1 1-^^ 
-e339931OU79<i-^61074 18 49 35 
4596G271071733678O8 " 7 ; 7 
576540231885.998153 • ft • M • HIHIHt 



A portion of the same dump specifying format X: 



USFR FIELD (FORMrtT=X) 



LX.IMP X.07 79254 09/11/79 



18 49 35 



O0v?OlOO 

oo^x^r04 

0000110 

©(?(>» 1 1;.4 
00001 70 

0lXH?204 
00OO:-'1O 
0000214 



4A4F4231393335O0 
0000000000000000 

0000000000000000 



00OOO0O0O0OOO0OO 
0OOOOOO(^>.X»<X>Oi:K.l 

00000O0O(XX)OO0f*.T 

44554r)'oO204&4F'V: 
31383A34393A333S 
6666666G6666G6G5 
40000002404 0O0S3 

*** END OF Di,)MP *** 



0O00eooo9O0opr0o 

8000000000000000 
OO0<?»?iOOi«1O0O0OOO 

OOOOOOO^H'OOOOOOi ^ 
O(.>0OOO0< HX^ >OOf>Oi 1 
30 T.V1 31.il<"f IVi 
4D41542'.>'..45'J504S 
OOOO(?OOOOO0(XXX)O 

ri2rioF4/Dfr38ns 

0800' 100000034 040 



O004OO9EOO009riSO 
OO0OO0CO»riO000OO0 
0000000000000000 

-or-j-j, >r- 3 1 3 1 :-T 3"^39 

li:i!!>i,14-.)'t3fVr-l.S, 

' ) ;o^x)i>a\)OoovHxx> 

F( (FFFFFFrFFFFFF 
C037Dr53B 1 rtSD 1 29C 
0(^3408004 OOOO0O0 



0OO7O0000OOO9D72 >.tOP1935 

0000000000000000 

0000000000000000 



Pf^RE 



09- 1 1/791 r 4? 35 



31 383A343'33A333'.; 

0(V>O<>'XXXXVOOOOO 

Oi,'0000000(^OOOii(X1 09'11 /"^IH 4'' 35 

30392^31^1^t•"3.':•^9 DUMP FORt^^T T\'f^.<. 03/11/79 

A72EEOfV2F.E0A72E 1 8 49 ■ 35 

3FCA8O0O0OOO0OOO " 7 . :• 

0800484948494849 * IW « ««' « HIHIHI 
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Format G specified on the same dump portion: 



USER FIELD (FORMfiT=:G) 



DUMP X.07 79254 e9/'ll/79 18 49 35 PAGE 



00C>01OO 


0. 677^139^79^8^794 


0OW>t04 


00e0©0e«000c 


00<»110 


000000000000 




***** 


0O(Wtf^ 


000000000000 


O<v)iM.>'0 


. W)0<}00<XH100<) 


p.^iiiAl 7^4 


000000000000 


0<?«»;;(>?i 


,?i0a?8rM790;M3:M 


ee'.>.:~<M 


0, 1816390G6368 -li:<9 


00<?0?10 


R 


00O<»14 


0.34347177O17?E:-O4 




««* f>ID OF DUMP *** 



0.000000000000 

. t>o0O'.?i0e(>oo00 

0000O000O000 

txPiOOOOOtlOOOO 
OOOOtXXXKiOOO 

Riwiwaci' j„vno;>i 
o(.xx)O0eo(XH>0 

OO0OO0OOOO0O 

. oooooo0i:M?)ooo 



0.0OO0O0000OO0 
0OO0O0OO0»>dO 
0(^0000000000 

. (XXXV«»0i.XX30 
lH)&TCiopf;>;g-n'J9 

iX^X)00O00OOO 

R 
-0.3O15031S1190e+17 

000000000000 



o.eoooooeoeooo 
oeoooooooefwe 
«xi000O00oeo 



J0B1935 



O^'ll^T^IR 4935 



isiP?90»;p3e8- 11:^1 

0,00vV>0O00OC00 

c<»ooooooi<oo o^^u^TPjR 4? y:- 

;?>t:?'G'?G0St5-121fi DLMP FORMtIT TMt? Crv-H^79 

-O , 15SOO830.^^J:.'-1912 IS 49 JS 

0.2;'75557561SeE-lG " ^ ; ? 

0i?OO0O000OOO 9 m 9 99 9 HIHIHI 



The same portion of the dump in format P: 



USER FIELD (FORMAT-P) 



DUt'f-"' X.07 79254 09/11/79 



18 49 35 POCf. 



1 



00001.00 045117 041061 034463 032400 

00iX)104 CXXWOO 000000 000000 000000 

OOOO110 0OOOOO 000000 000000 000000 

****-f 

0OO0164 0O00O0 000000 000000 OOOOOO 

0000170 0OOO<?O 000000 000000 OOOOOO 

0OOO174 0000i>0 000000 OOOOOO OOOOOO 

oooo:oo 04<^tr.:s o^xev^i 02OI0G 047^,;:,? 

0O»;1O.'O4 0T0470 O'-fl^OC'l 0'M4Xr! 03t'1(^'^ 

0000.10 06:il4G 0G3t46 06314G 0e3t45 

0friOOc~l4 04001?© 000003 040100 0OO:?P3 
*** END OF DUMP *** 



OOOOOO 000000 110000 137000 

looooi? ooi;'00o ooootw ooootxi 
OOOOOO ooo*y>o oooooo oooooo 



OOOOOO 

0OOO<X'i 

0.10071. 

O'lr.soi 

fH.lOOO(1 

01044;: 

00400>? 



OOOOpiO 
00«)0<H? 

OOIXVHI 

oio:«r4 

040000 



oooooo oooooo 

txxioo*? <x>oooo 

0304 ^i 7 o:^3471 

os2i:u iv ,01011 

^KX>\10 OOOOiX) 

o'(,-r.i too4a.; 

0CWii3 0'I010<1 



000004 000236 000000 116600 
oooooo (<O0O00 oooooo 000000 
oooooo 000000 oooooo 000000 



030071 027461 

oooooo oooooo 

030470 035064 
051400 oooooo 
177/7/ 1777/7 
140067 153073 
000204 004000 



030457 
OOOOOO 
0344^2 
IXV3000 
1 :^,'/77 
015215 
O'lOOOO 



033471 
000000 
031465 
0(^0000 

i:'7777 
011234 
O^^OOOO 



00000' 000000 000000 116562 
OOOOOO OOOOOO oooooo OOOvXW 
000000 000000 000000 oooooo 



030470 

oooooo 
oooooo 

030071 
123456 
03.7712 
004000 



035064 
0<ViOOO 
OOOOOO 
027461 
lti024 7 
li?iOOOO 
044111 



03447? 
OOOOOO 
01.10000 

03045'^ 
0.^"'340 
OiXXXKi 
014111 



031465 
OOOOOO 
OO»XTO0 

03:«.'i 

IcTJ'"^ 

OOiXXX^ 
044111 



The same portion of the dump in format M: 



USER FIELD (FiJRMAT^) 



J0B1935 

0000100 4511741061 3446332400 00O0OOOOOO 9OO0Op-'OOO 

0000104 OOOOOO0000 OO0OO0OO>)O 800000001.10 Ot.M.XiOi?OOOi.l 

0000110 0000000000 0000008000 OOO0Ot)OOO0 oooooooooo 

***** 

OOOOUVt 0000000000 0000000000 0OO0OOO0«?(0 01X10000000 

00^). '0 0000000000 0000000000 0000000000 00O000Ov)C»? 

0OOe.i.74 0000000000 0000000000 3O0;-'1274G1 3045733471 

0O(»r!»-<0 4212546520 2010647522 4650152040 521.?1S0105 

OOOOC^M 3047035064 34472314CS 0OO0t»O0OiX> 0O(')000000O 

0000210 6314663146 6314663145 10442103G4 7t-;/51K0425 

0000214 4000000002 4O1000O2O3 0400040000 00OO3401O0 
*** END OF DUMP *** 



DUMP X.07 79254 03/11/79 



18 49 35 



000040023G 0000096600 
0<VXX?fH<O0O OOi-iOOOOOOO 
OOfOOOlXIOll O0>?OOOOOOO 

300712V461 3045733471 

0000000000 0000000000 

30470 1'.U'OI 3-14 723 1405 

5140OO>XX)O OOOOOOtWOO 

F 77771- 7;'77 F7777f-"V777 

C006''IX!073 15i:i511234 

0O,^04i>lO0O 4OOOO00GO0 



0000700000 O0O(X3'T6562 J0\ 
OOOOOOiXiOO OOOOVXIOOOO 

oootxaooooo ooocxiooooo 

304703'.;064 3447231465 

OOOOOOO»X30 0000000000 

OOOOOOOCOO 0000000000 

:>O07127461 3045733471 DUMP FORIVlT TYPE? 

A3456E0247 27340A3456 18 49 35 

3771280000 0000000000 

0400044111 4411144111 § W « «« 



09/11/7918 49-36 



09/ll-'791S A9 35 



«i/ll-<^ 



HIHIHI 
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DEBUG - PRODUCE SYMBOLIC DUMP 

The symbolic debug utility routine, DEBUG, provides a means of dumping 
portions of memory and interprets the dump in terms of FORTRAN or CAL 
symbols. DEBUG is normally used when a job aborts after an EXIT, 
DUMPJOB sequence, however it may be used anywhere provided that a 
valid version of $DUMP exists. 

To be useful, both CFT and CAL must write special tables, which the 
loader (LDR) augments with a version of the load map. The loader 
writes this information on a dataset called $DEBUG, which gives the 
FORTRAN or CAL symbol names associated with memory addresses. This is 
initiated by specifying the ON=Z option for CFT or the SYM option for 
CAL. DEBUG reads $DEBUG and $DUMP and prints out variable names and 
values in a format appropriate for the variable type. 

The following example shows the conventional use of DEBUG: 

JOB , ... . 

CFT,ON=Z. 
LDR. 
EXIT . 
DUMPJOB . 
DEBUG . 



The library routine SYMDEBUG may be called from either FORTRAN or CAL 
with one argument, which is a Hollerith string containing any of the 
DEBUG parameters. SYMDEBUG produces output similar to that produced 
by DUMP but interprets the memory of the running program rather than 
$DUMP. 



Format : 



DEBUG , I =idn , O=odn , Ti\m9=ddn , TRACE=n , SYMS=S2/m , N0TSYMS=nz/8OT , 



MAXDIM=d-i/W, BLOCKS=fcZ?C ,N0TBLKS=w2?Z/C ,PAGES=np ,COMMENTS= ' string' . 
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Parameters are in keyword form. 

l=-icin Name of dataset containing debug symbol tables. The 

default is $DEBUG, which is created by the loader from the 
symbol tables produced by CFT and CAL. 

0=oan Name of dataset to receive the listing output from the 

symbolic debug routine. The default is $OUT, 

DUMP=(i<:^ Name of dataset containing the dump of the user field. 
This dataset is created by the DUMPJOB control 
statement, ddn is used when the symbolic debug routine is 
invoked after an abort. The default is $DUMP. 

TRACE=n Number of routine levels to be looked at in symbolic dump. 
DEBUG traces back through the active subprograms the number 
of levels specified by n. If this parameter is omitted or 
if TRACE is specified without a value, the default is 50. 

SYMS=8Z/m List of symbols to be dumped by DEBUG. Up to 20 symbols 
may be specified; symbols are separated by a colon. A 
shorthand notation as described in the AUDIT statement may 
be used; thus, a dash represents any character or 
characters or no character, and an asterisk represents any 
single character. For example: 

... ,SYMS=ABC:X-:B**, ... 

requests a dump of the symbol ABC, all symbols that start 
with X, and all 3-character symbols beginning with B. This 
parameter applies to all blocks dumped. The default is all 
symbols. 

N0TSYMS=na2ym 

List of symbols to be skipped. Up to 20 symbols may be 
specified; symbols are separated by a colon. The shorthand 
notation as described under the SYMS parameter may be 
used. This parameter applies to all blocks dumped. The 
default is that no symbols are to be skipped. This 
parameter takes precedence over the SYMS parameter. 



MAXDIM=diw2 



Maximum number of each dimension of the arrays to be 
dumped. This parameter allows the user to sample the 
contents of arrays without creating huge amounts of 
output. For example: 

... ,MAXDIM=3:2:3, ... 
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causes the following elements to be dumped from an array 
dimensioned as A(10,3,6): 

A(l, 1, 1) A(2, 1, 1) A(3, 1, 1) A(l, 2, 1) A(2, 2, 1) 

A(3, 2, 1) A(l, 1, 2) A(2, 1, 2) A(3, 1, 2) A(l, 2, 2) 

A(2, 2, 2) A(3, 2, 2) A(l, 1, 3) A(2, 1, 3) 

A(3, 1, 3) A(l, 2, 3) A(2, 2, 3) A(3, 2, 3) 

This parameter applies to all blocks dumped. The default 
is MAXDIM=20:5:2:1:1:1:1. The arrays are dumped in storage 
order. 

BLOCKS=b^?C 

List of common blocks to be included in the symbolic dump. 
A maximum of 20 blocks may be specified. The shorthand 
notation as described under the SYMS parameter may be 
used. All symbols (qualified by the SYMS and NOTSYMS 
parameters) in the blocks named here are to be dumped. If 
BLOCKS is specified without a value, t all common blocks are 
dumped . 

N0TBLKS=?2-b^/c 

List of common blocks to be excluded from the symbolic 
dump. A maximum of 20 blocks may be specified. The 
shorthand notation as described under the SYMS parameter 
may be used. The default is to exclude no blocks. NOTBLKS 
specified without a value excludes all but the subprogram 
block. This parameter takes precedence over the BLCXZKS 
parameter. 

PAGES=np Page limit for the symbolic debug routine. The default is 
70 pages. 

COMMENT= ' string ' 

Identifier to be printed on the DEBUG output title line. 
Up to 8 ASCII characters may be specified. 



DSDUMP - DUMP DATASET 

The DSDUMP control statement dumps specified portions of a dataset to 
another dataset. The dump may be made in one of two formats: blocked or 
unblocked. 

In the blocked format, a group of words within a record, a group of 
records within a file, and a group of files within a dataset may be 
selected. Initial word number, initial record number, and initial file 
number begin with 1 and are relative to the current dataset position. 
Specifying an initial number greater than one causes words. 
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records, or files to be skipped starting from the current position. 
Since the initial word, record, or file number is relative to the current 
position of the dataset, the dataset must be positioned properly prior to 
calling DSDUMP. A rewind of the dataset prior to calling DSDUMP makes 
the initial word, record, and file numbers relative to the beginning of 
the dataset. When DSDUMP is completed, the input dataset is positioned 
after the last record dumped. 

The unblocked format is used for dumping a dataset without regard to 
whether it is blocked. It is possible to dump a blocked dataset in 
unblocked format (by sectors) . A group of sectors within the dataset or 
a group of words within each sector may be selected. The initial word 
and initial sector numbers begin with one and are always relative to the 
beginning of the dataset. Specifying an initial sector greater than 1 
causes sectors to be skipped from the beginning of the dataset; 
specifying an initial word greater than one causes words to be skipped 
from the beginning of each sector. Following a dump in unblocked format, 
the dataset is closed. 



Format: 



DSDUMP ,l=idn , 0=odn , DF=d/ , IW=7^ , NW=n , lR=n ,NR=n , lF=n ,NF=n , is=n ,NS=n . 



Parameters are in keyword form; the only required parameter is I. 

l=idn (or DN=idn) 

Name of dataset to be dumped. This is a required parameter 

0=odn (or 'L=odn) 

Name of dataset to receive the dump. The default is $OUT. 

DF=df Dump format. The default is B. 

B Blocked 
U Unblocked 

IW=?2 Decimal number (n) of initial word for each record/sector 
on idn. The default is 1. 

NW=n Decimal number {n) of words per record/sector to dump. 

Specifying NW without a value dumps all words to the end of 
a record/sector. The default is 1. 
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lR=n 



Decimal number (n ) of initial record for each file 
on idn. Applicable only if DF=B. The default is 1, 



NR=n Decimal number {n) of records per file to dump. 

Specifying NR without a value dumps all records to the 
end of the file. Applicable only if DF=B. The default 
is 1. 



IF=n 



NF=« 



lS=n 



NS=n 



Decimal number {n} of initial file for dataset on idn. 
Applicable only if DF=*B. The default is 1. 

Decimal number (n) of files on idn to dump. Specifying 
NF without a value dumps all files to the end of the 
dataset. Applicable only if DF=B. The default is 1. 



Decimal number (n) of initial sector on idn. 
only if DF=U. The default is 1. 



Applicable 



Decimal number (n) of sectors to dump. Specifying NS 
without a value dumps all sectors to the end of the 
dataset. Applicable only if DF=U. The default is 1. 

For blocked format, each record from idn dumped to odn is preceded by 
a header specifying the file and record number. For unblocked format, 
each sector is preceded by a header specifying the sector number. 



Format of each dump record: 



Word count 


Octal interpretation 
of four words 


Character interpretation 
of four words 



A row of five asterisks indicates that one or more groups of four 
words has not been formatted because they are identical to the 
previous four. Only the first group is formatted. The number of 
words not formatted can be determined from the word counts of the 
formatted lines before and after the asterisks. The final group of 
four or less words is always formatted. 
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COMPARE ~ COMPARE DATASETS 

The COMPARE control statement compares two blocked datasets and lists all 
differences found. The output consists of a listing of the location of 
each discrepancy, the contents of the differing portions of the datasets, 
and a message indicating the number of discrepancies. Refer to the 
CRAY-OS Message Manual, publication SR-0039. 

Keyword parameters allow the user to specify the maximum number of errors 
and the amount of context to be listed. 

If only parts of two datasets are being compared, the parts must first be 
copied before using a COMPARE statement; COMPARE compares complete 
datasets only. 

COMPARE rewinds both input datasets before and after the comparison. 



Format : 



COMPARE fK=adn , B=bdn , L=Zdn , DF=df ,ME-maxe ,CP=epn , 



CS=csn,CW=ci<?]L' !cz<?2'^^^^'^~<^^" 



Parameters are in keyword form; both A and B must be specified. 

h=adn and B=bdn 

Input dataset names. If adn^hdn, an error message is 
issued and the job is aborted. A and B are required 
parameters. 

'L-tdn Dataset name for list of discrepancies, tdn must be 

different from adn and hdn. The default is $OUT. 

DF=df Input dataset format. The default is T. 

df is a 1-character alpha code as follows: 

B Binary. The input datasets are compared logically 
to verify that they are identical. If they are not 
identical, the differing words are printed in octal 
and as ASCII characters. The location printed is a 
word count in decimal. The first word of each 
dataset is called word 1. 



Part 2 
SR-0011 8-11 J-01 



T Text. The input datasets are compared to see if 
they are equivalent as text. For example, a 
blank-compressed record and its expansion are 
considered equivalent. If the two datasets are 
not equivalent, the differing records are printed 
as text. The location is printed as a record 
count in decimal. The first record of each 
dataset is called record 1, 

ME=maxe Maximum number of differences printed. The default is 
100. 

CP^epn Amount of context printed, cpn records to either side 
of a difference are printed. The CP parameter applies 
only if DF=T; if DF=B and CP are specified, an error 
message is generated. The default is 0, 

CS^csn Amount of context scanned, esn records to either side 
of a discrepancy are scanned for a match. The CS 
parameter applies only if DF=T; if DF=B and CS are 
specified, an error message is generated. The default 
is 0. 

If a match is found within the defined range, subsequent 
comparisons are made at the same interval. That is, if 
record 275 of dataset A is equivalent to record 277 of 
dataset B, the next comparison is between record 276 of 
dataset A and record 278 of dataset B. 



NOTE 

If identical records occur within esn 
records of each other, the pairing is 
ambiguous and COMPARE may match the wrong 
pair. 



Oi^=ow or CVi=eW2^teW2 

Compare width. If CVJ=ew is specified, columns 1 
through ew are compared. If CW'=<3i(?i:(3W2 ^^ 
specified, columns aw-^ through 0W2 are 
compared. Specifying CW without a value is not 
permitted. The default is to compare columns 1 through 
133, but this can be changed by installation option. 
The CW parameter applies only if DF=T; if DF=B and CW 
are specified, an error message is generated. 
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AB0RT=t2(3 If ae or more differences are found, the job step aborts. 
Specifying ABORT alone is equivalent to AB0RT=1 and causes 
an abort if any differences are found. Specifying ABORT 
does not prevent the listing of up to rmxe differences. 



PRINT - WRITE VALUE OF EXPRESSION TO LOGFILE 

The PRINT control statement writes the value of an expression on the 
logfile. The value of the expression is written in three different 
formats: as a decimal integer, as a 22-digit octal value, and as an 
ASCII string. PRINT is a system verb. 



Format: 



PRINT ^ex-pveesion ) 



Parameters: 

expression 

Any JCL expression (part 1, section 4). This parameter is 
required. 

Format in the logfile: 

FT060 deeimdl octal ASCII 

FT060 Message code indicating origin is PRINT statement 

decimal 16-digit decimal representation of evaluated expression 

octal 22-digit octal representation of evaluated expression 

ASCII 8-character ASCII representation of evaluated expression 
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FLODUMP - FLOW TRACE RECOVERY DUMP 

The FLODUMP control statement recovers and dumps flow trace tables when a 
program aborts with flow tracing active. The flow trace tables are 
dumped in the FORTRAN flow trace format. 

FLODUMP is invoked by specifying the F option on the CFT control 
statement and including the FLODUMP control statement in the COS control 
statement file. (Refer to the CRAY-1 FORTRAN (CFT) Reference Manual, 
publication SR-0009, for more information on the F option.) 



Format: 



FLODUMP. 



Parameters: none 

The following example illustrates the use of the FLODUMP control 
statement. 

JOB, 

CFT, ON=F. 
LDR. 
EXIT. 
DUMP JOB . 
FLODUMP . 



A flow trace summary is illustrated in figure 8-1; a flow trace recovery 
dump is shown in figure 8-2. 

The examples in figures 8-1 and 8-2 show that the total time reported for 
the main program, ONF, is larger for the flow trace recovery dump than 
for the flow trace summary. This difference is because the time reported 
with FLODUMP includes the main program's execution time, the time 
required to abort the program, and the time required to recover the flow 
trace tables. 
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FLOW TRACE 


SUMMARY 


















ROUTINE 




TIME 


% 


CALLED 


AVERAGE T 






1 


ONF 




0.000053 


5.42 






1 


0.000053 






















CALLS 


SUBl 


2 


SUBl 




0.000323 


32.80 






9 


0.000036 CALLED 


BY 


ONF 


















CALLS 


SUB2 


3 


SUB2 




0.000322 


32.75 






9 


0.000036 CALLED 


BY 


SUBl 


















CALLS 


SUB3 


4 


SUB 3 




0.000286 


29.04 






9 


0.000032 CALLED 


BY 


SUB 2 


*** 


TOTAL 




0.000985 
















Is-k* 


OVERHEAD 




0.000712 
















SUBROUTINE LINKAGE 


OVERHEAD 


SUMMARY 








28 CALLS 








MINIMUM MAXIMUM AVERAGE 


CYCLES SECONDS 




% 


T REGISTERS 




1 


2 


2 


.0 




838 1.05E-05 


1. 


0640 


B REGISTERS 




2 


3 


3. 







894 1.12E-05 


1.. 


L351 


ARGUMENTS 


















O.OOE+00 


0. 


DOOO 




TOTAL 














1732 2.17E-05 


2.. 


L991 


MAXIMUM SUBROUTINE DEPTH = 


4 















Figure 8-1. Example of a flow trace summary 



FLOW TRACE RECOVERY DUMP • 


— RECOVER WITH 


ONFDMP ACTIVE 




FLOW 


TRACE 


SUMMARY 












ROUTINE 


TIME 


% 


CALLED 


AVERAGE T 




1 


ONFDMP 


0.000328 


26.04 


1 


0.000328 

CALLS 


SUBl 


2 


SUBl 


0.000323 


25.64 


9 


0.000036 CALLED BY 
CALLS 


ONFDMP 
SUB2 


3 


SUB2 


0.000322 


25.61 


9 


0.000036 CALLED BY 
CALLS 


SUBl 
SUB3 


4 


SUB3 


0.000286 


22.70 


9 


0.000032 CALLED BY 


SUB 2 


*** 


TOTAL 


0.001259 










• ** 


OVERHEAD 


0.000712 










SUBROUTINE LINKAGE OVERHEAD 


SUMMARY 


28 CALLS 






MINIMUM MAXIMUM 


AVERAGE 


CYCLES SECONDS 




T REGISTERS 


1 


2 


2.0 


838 1.05E-05 


0.83 


B REGISTERS 


2 


3 


3.0 


894 1.12E-05 


0.88 


ARGUMENTS 








0.0 


O.OOE+00 


0.00 




TOTAL 








1732 2.17E-05 


1.71 


MAXIMUM SUBROUTINE DEPTH = 


4 









Figure 8-2. Example of a flow trace recovery dump 
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SYSREF - GENERATE GLOBAL CROSS-REFERENCE LISTING 

The SYSREF utility generates a global cross-reference listing for a group 
of CAL or APML programs. The number of CAL or APML programs that can be 
included in such a group is limited by the amount of CRAY-1 memory 
allocated to a user. 

SYSREF reads special binary symbol tables written by CAL or APML and 
produces a single cross-reference listing for the program modules 
represented in the tables. When the X parameter appears on a CAL or APML 
statement, a record is written for each program unit assembled. The 
records are written to a dataset specified by the X parameter ($XRP by 
default if X appears alone) . Each record has a header containing the 
name of the program unit. The rest of the record consists of 
cross-reference information for every global symbol used in that program. 



Format: 



SYSREF , x=xdn , L=ldn . 



Parameters: 



X=ocdn Name of dataset whose first file (normally the only file) 

contains one or more symbol records written by CAL and/or 
APML. The default is $XRF. 

L=ldn Name of output dataset. The default is $OUT. 



USE OF SYSREF 

SYSREF is usually used to process symbol records written by CAL and/or 
APML earlier in the same job. To do so, add X parameters to each CAL or 
APML control statement and follow them with a SYSREF control statement: 



CAL,X. 

APML,X. 

CAL,X. 

SYSREF, L=XROUT. 
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$XRF is used as default in all cases. 

To process symbol records written in an earlier job, the following 
sequence is used: 

The first job: 
CAL,X. 
APML,X. 
SAVE,DN=$XRF,ID=XX. 

The second job: 

ACCESS , DN=$XRF , ID=XX , UQ . 
DELETE, DN=$XRF. 
SYSREF,L=XROUT. 

To add more symbol records before invoking SYSREF, use: 

ACCESS, DN=$XRF,ID=XX,UQ. 

DELETE, DN=$XRF. 

SKIPR,DN=$XRF,NR. 

CAL,X. 

SYSREF 

The format above has the same effect as if the CAL step had been done 
before the SAVE step. 



GLOBAL CROSS-REFERENCE LISTING FORMAT 

The global cross-reference listing contains only global symbols. A 
symbol is global if it is any one of the following: 

• Named in an ENTRY or EXTERNAL statement 

• Defined before an IDENT statement and after the preceding END 
statement 

• Defined within a system text such as $SYSTXT 

• Defined within a section of source code bracketed by TEXT and 
ENDTEXT pseudo instructions 

The order of the symbols in the global cross-reference listing is 
lexicographic, based first on the symbol name and then (within each 
symbol name) on the module name. An exception to the order is made for 
symbol names beginning with N@, S@, or W@. These symbol names are sorted 
as if @ is the most significant (leftmost) character and the N, S, or W 
is the least significant character. The listing displays the symbol name 
correctly. The effect is a grouping of all the N@, S@, and W@ symbols 
that refer to the same field in a table. 
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The global cross-reference listing consists of 13 columns: 



Column Heading 



Contents 



Value 

Symbol 

Origin 



4 Module 
5-13 References 



The symbol's value 

The symbol's name 

The IDENT of the system text in which the symbol 

is defined; or the label of the TEXT block in 

which the symbol is defined; or *GLOBAL*, if the 

symbol is defined outside any program unit; or 

blank. 

The IDENT of the module within or before which 

the symbol is defined or referenced 

A list of the lines on which the symbol is 

defined or referenced 



The symbol's name, value, and references appear in the same format as in 
a CAL or APML listing. The page number in each reference is a local page 
number which starts at 1 for each module. In a CAL or APML listing, this 
is the page number that appears in parentheses to the right of the second 
title line on each page. 
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RELOCATABLE LOADER 



The COS relocatable loader is a utility program that executes within 
the user field and provides the loading and linking in memory of 
relocatable modules from datasets on mass storage. 

The relocatable loader is called through the LDR control statement 
when a user requires loading of a program in relocatable format. 
Absolute load modules can also be loaded. The design of the COS 
loader tables and relocatable loader allows program modules to be 
loaded, relocated, and linked to externals in a single pass over the 
dataset being loaded. This minimizes the time spent in loading 
activities on the CRAY-1. The loader allows the immediate execution 
of the object module or the creation of an absolute binary image of 
the object module on a specified dataset. Loader features are 
governed by parameters of the LDR control statement. 

The relocatable loader can also generate a partially relocated 
module. This module is referred to as a relocatable overlay and is 
described at the end of this section. 



LDR CONTROL STATEMENT 

The loader is called into execution by the LDR control statement. 
Parameters of the control statement determine the functions to be 
performed by the loader. 



Format : 



LDR,DN=dn,LlB=Z.dn,NOLlB=l(in,LLD,AB=adn,MAP=op,SlD='et?^ng'' ,T=t7»a, 



NX,DEB=^,C,0VL=dir»,CNS,NA,USA,L=Zdn,SET=t;aZ,E=n,I=8dir», 
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Parameters are in keyword form. 

DN=dn Dataset containing modules to be loaded. The default is 
$BLD. Loading continues until an end-of-file is 
reached. Modules are loaded according to block name as 
determined by a CAL IDENT card or a CFT PROGRAM, 
SUBROUTINE, BLOCK DATA, or FUNCTION statement. Duplicate 
blocks are skipped and an informative message is issued. 

Multiple files from the same dataset may be loaded by 
specifying the dataset name multiple times separated by 
colons. A maximum of eight files may be indicated. 

Datasets specified by the DN parameter are closed at the 
end of the load process. Closing a dataset has the 
effect of rewinding the dataset and releasing I/O tables 
and buffers. 

Modules to be loaded may be relocatable or absolute. 
However, the two types of modules may not be mixed. 

For example, 

DN=L0AD1 : L0AD2 : $BLD 

causes the loading of all modules in the first file of 
datasets LOADl, then L0AD2, and then $BLD. 

Normally the dataset is rewound before loading; however, 
consecutive occurrences of a dataset name inhibit 
subsequent rewind operations. Therefore, the statement 

DN=L0AD3:L0AD3 

causes the loading of all modules in the first two files 
of dataset LOADS. 

The DN parameter takes on a special quality when OVL is 
specified: only one dn may be specified. The dataset 
named will be the initial LOAD file used by the overlay 
loader. (See the description of the overlay loader, part 
2, section 10 for more information.) 

LlB=ldn The LIB parameter names the dataset from which 

unsatisfied externals are loaded. A maximum of eight 
datasets can be named, with the dataset names separated 
by colons. All datasets listed ate automatically 
accessed if not already local; therefore, no ACCESS 
statement is required. 
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Any default libraries are automatically included in the 
library list unless the NOLIB parameter is specified. 
The loader accesses the default libraries if they are 
not local to the job; no ACCESS statement is required. 

Datasets specified by the LIB parameter are closed at 
the end of the load process. Closing a dataset has the 
effect of rewinding the dataset and releasing I/O tables 
and buffers. 



NOTE 

These datasets should be generated using the 
BUILD utilities to prevent unnecessary 
overhead in the loader. 

The libraries cannot be tape resident. 



The NOLIB parameter value names the specific default 
library to be excluded from the load. Selecting NOLIB 
with no value specifies the exclusion of all default 
system libraries. If NOLIB is not specified, any 
default libraries that a site has are automatically 
included in the library list, along with any libraries 
specified on the LIB parameter. 

LLD Specifying the LLD parameter causes any libraries 

included in the load to be retained as local datasets at 
load completion. These local datasets remain open. If 
the LLD parameter is not specified, the loader closes 
all libraries at load completion. Datasets 
automatically accessed are not released at load 
completion. 

AB=a(in Absolute binary object module generation. Use of this 
parameter causes an absolute binary object module to be 
written to the named dataset after the load process is 
completed. Selecting AB does not imply NX (no 
execution) . Unless NX is also selected, the loaded 
program begins execution after the binary is generated. 
Specifying AB without adn causes the module to be 
written on a dataset named $ABD, the default dataset. 
Some other dataset may be specified by KB-adn, The 
dataset is not rewound before or after the file is 
written. 
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If the AB parameter is omitted, no binary generation 
occurs. 

If OVL is specified on the loader statement, the OVLDN 
directive replaces AB; any value specified for AB is 
ignored in overlay mode. (See part 2 section 10 for a 
detailed description.) 

MAP=c>p Map control. The MAP parameter causes the loader to 
produce a map of the loaded program on the specified 
dataset. MAP can take any of the following values: 

ON Produces a block list and an entry list 

including all cross references to each entry. 

FULL Same as MAP=ON. 

OFF No map is produced. MAP=OFF is the default. 

PART Produces a block list only. Equivalent to MAP 
with no value specified. 

S1D=^ string* 

Debug routine loading. The SID parameter indicates the 
system debugging routines (SID) are to be loaded with 
the code. These routines comprise an additional binary 
dataset loaded after all DN specified datasets and 
before any libraries. 

The * string* , if provided, is passed to SID for 
evaluation as a control statement. The verb and initial 
separator are not required. For example, 
SID='I=IN,ECH=ELIST. ' is a proper string specification 
(the period is a required terminator) . For a complete 
description of SID parameters, see the Symbolic 
Interactive Debugger (SID) User's Guide, CRI publication 
SG-0056. If only SID is specified, all keyed default 
SID control statement parameter values are used. 

T^tva Transfer name. The T parameter allows specification of 

an entry name where the loader transfers control at 
completion of the load. The T parameter also specifies 
the entry included in absolute binary object modules. 

The entry name is a maximum of eight characters. If no 
T parameter is specified, the loader begins object 
program execution at either the entry specified by the 
first encountered START pseudo from a CAL routine or at 
the entry of the first main program in CFT compiled 
routines. If no START entries are encountered, a 
warning message is issued and the first entry of the 
first relocatable or absolute module is used. 
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NOTE 

When the SID parameter is used, the load transfer is to 
the system debugger; the T parameter is ignored and a 
warning message is issued to the user logfile. 



NX No execution. Inclusion of this parameter inhibits 
execution of the loaded program. 

DEB=Z Job Communication Block (JCB) length. The default 
length is 200g. Specifying DEB without a value 
changes the JCB length to 3OOO3. 

C Compressed load. This parameter causes loading of each 
module to begin at the next available location after the 
previous module. If this parameter is omitted, loading 
of modules begins on 208-word boundaries only 
(optional load) . 

OVL-div Overlay load. The OVL parameter indicates an overlay 
load sequence is specified on dir, (See part 2 
section 10 for a detailed description of the overlay 
load.) If the OVL keyword is specified without a value, 
the loader examines the next file of $IN for an overlay 
load sequence. The default is no overlay load. 
Selecting OVL implies NX (no execution) . 

CNS Crack next control statement record image. This feature 
allows the loader to pass parameters on to the loaded 
program for analysis and use during execution of the 
loaded program. The control statement cracked follows 
the LDR control statement and is not available for 
processing by the Control Statement Processor (CSP) 
after processing by the loaded program. 



NOTE 

When the SID parameter is specified, the CNS parameter 
is ignored and a warning message is written to the user 
logfile. SID prompts for the control statement for the 
code being debugged. 
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NA No abort. If this parameter is omitted, a caution or 
higher level loader error causes the job to abort. 

USA Unsatisfied external abort. When USA is specified, the 
loader aborts at the end if it finds one or more 
unsatisfied externals. A load map listing all 
unsatisfied externals is produced, if called for. 

L='tdn Listing output. This parameter allows the user to 

specify the name of the dataset to receive the map 

output. If L^O, all output is suppressed. The default 
is $OUT. 

SET=vat Memory initialization. Variables, named and blank 

common blocks, and storage areas defined by DIMENSION 
statements are set to 0, -1, or an out-of-range 
floating-point value during loading. The default is an 
installation option. 

SET=ZERO Memory is set to binary zeros. 

SET=ONES Memory is set to -1 (all bits set in word) . 

SET=INDEF Memory is set to a value that causes an 

out-of-range error if the word is referenced 
as a floating-point operand. The I's 
complement of each memory address is placed in 
the lower 24 bits of the respective word to 
aid in reading register and memory dumps. An 
example, in octal, of the value loaded into 
memory word 13216 is: 0605050037740177764561. 
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E=n Lists error messages. This parameter indicates which 
level of loader-produced error messages are not to be 
listed. The user may specify one of five levels of 
severity, where n is the highest level to be 
suppressed. The default for this parameter is E=2. 



Level Type Description 

1 COMMENT Error does not hinder program 

execution. 

2 NOTE Error probably hinders program 

execution. 

3 CAUTION Job aborts when load process 

completes unless NA is selected? 
program might not execute properly. 

4 WARNING Job aborts when load process 

completes unless NX is selected; 
program execution is not possible. 

5 FATAL Job aborts immediately. 

Example : 

E=2 suppresses COMMENT and NOTE messages and allows 
CAUTION, WARNING, and FATAL messages to appear. FATAL 
messages are never suppressed. 

l=sdir Selective load. Modules from other datasets may be 
loaded according to a set of directives, sd'ir 
indicates the dataset containing the directives. If the 
I keyword is specified without a value, the directives 
are taken from the next file of $IN. The selective load 
directives are described later in this section. 



LOADER ERRORS 

Following is a list of the errors encountered by the loader. The 
errors are listed by class. 



Comment : 



Blank common redefined 

Named common redefined smaller 

Generating BUILD directory for Library 
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Note: 



Caution: 



Warning 



Fatal : 



All files searched 
Name included before 
Name excluded before 



Overlay member not found 

Multiple load datasets ignored in overlay mode 

Illegal map value 

No start address found - first entry used 

Duplicate entry loaded and ignored 

Duplicate program block name encountered and skipped 

Bad directory format on library dataset 

Unsatisfied external 

Disabled parameter selected and ignored 

Dataset replaced by file DN 

Invalid read, try again 

No selective modules from dataset 

Skip dataset included before 

Invalid selective file 



Blank common address not large enough 

Dataset name too long 

Named common defined larger 

Relocatable load module in absolute mode 

Member error 

Directive error 

Illegal character in overlay directive 

Compile error 

Transfer is to SID; T parameter ignored 

SID loaded; CNS parameter ignored. 

Absolute load module in relocatable load 



Start entry not found 

Bad XI field in External Relocation Table (XRT) table 



More than one internal relocation block 

Invalid table type 

Unable to open specified dataset 

Null file or abnormal table found 

Invalid program block name 

Initial table not Program Description Table (PDT) 
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LOAD MAP 

Each time the loader is called, the user has the option of requesting 
a listing that describes where each module is loaded and what entry 
points and external symbols were used for loading. This listing is 
called a load map. 

The user may specify the contents of the map or the dataset to receive 
the map by setting parameters of the LDR control statement to the 
desired values. The MAP parameter of the LDR control statement allows 
the user to specify the contents of the map requested. MAP=ON or 
MAP=FULL produces a block list and an entry list. The block list 
gives the names, beginning addresses and lengths of the program and 
subroutines loaded on this loader call; the entry list includes all 
cross references to each entry. MAP=PART supplies a partial map, that 
is, the block map only. 

The load map is printed when requested even if fatal errors abort the 
load. In this case, the map contains only those modules loaded up to 
the point where the fatal load error occurred. 

Figure 9-1 illustrates the load map generated by the following LDR 
statement: 

LDR , DN=$BLD : L0AD2 , LIB=MyLIB : $FTLIB ,MAP=FULL . 

The block list consists of items 1-16 in figure 9-1; the entry list 
includes items 17-21, 

1. Job name from the JOB control statement 

2. Loader level and Julian date of assembly of the loader 

3. Date and time of loader execution 

4. Page number 

5. Load type; either relocatable, absolute, or overlay 

6. Entry name to which initial transfer is given 

7. Entry address where initial transfer is made 

8. Name of load or library dataset containing modules to be 
loaded 

9. Names of blocks loaded from the named dataset. These are 
common blocks (identified by the slashes around their names, 
for example, /LABEL/) or are names of program blocks. 
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♦SYSTEM is always the first block listed in a relocatable 
load. It consists of the first 200g words of the user 
field, which is reserved for the Job Communication Block 
( JCB) . For an absolute load, *SYSTEM is not allocated. 
Therefore, the CAL user must set the origin to 200 g via an 
ORG pseudo instruction to allow space for the JCB. If this 
is not done, the job will abort. 

Blank common, indicated as //, is allocated last and appears 
at the end of the list (if it has been defined). 



SftMPL 

© 



RELOCRTRBL.E LORD 
LOAD TRANSFER IS TO 



© 
© 



.DR 1 02 78173 

^©^ 



07/13/78 



® ® ® 



DRTRSET 



$BLD 



L0fiD2 
tlYLIB 



$FTLIB 



a.OCK 

*SYSTEM 

MRINPRG 

/GLOBAL 

SUB01 

/LABEL 

rmi 1 

SLIBS 

SUBll 

SIJB03 

SEND 

SEXIT 



ADDRESS 


360 
200 
156a 
1410 
1640 
1700 
1720 
2000 
20G0 
2120 



AT ( (7) 

© 

LENGTH 

200 
1030 

144 
60 

146 
25 
1 
43 
42 
25 
16 



® ® ® ® 



DATE 



OS REU 



PROC. 



UERl 



07/13/78 07/15/78 CFT 1.02 06/22/78 

07/13/78 07/12/78 CFT 1.02 06/22/78 

07/13/78 07/12/73 CFT 1.02 06/22/78 

07/13/78 07/12/79 CAL 1.02 78173 

07/13/78 07/12/78 CFT 1.02 06/22/78 

07/13/78 07/12/78 CFT 1 02 06/22/78 

06/22/78 05/24/78 CAL 1 01 78104 

06/22/78 05/24/78 CAL 1.01 78104 



©■ 



14: 58: 05 



PAGE 



© 



® 

COMMENT 



$RCW 


5400 


267 


06/22/78 


05./24/7S CAL 1.01 78104 




• — ■ _ 




// 


5667 


144 












® 


® 




® 


@ 








BLOCK NAME 


ENTRIES 




e:ntry urlue 


RBSOLUTE references 








MftlNPRG 


MRINPRG 




1371a 










SUB01 


SUB01 




1565a 


1374d 








FUNll 


FUNll 




i645a 


162 la 16?lc 1622b 








SUBS 


SUB02 




1700a 


1375c 








SUBll 


SUBll 




1725a 


lB14a 








SUB03 


SUB03 




2012a 


1376b 








SEND 


SEND 
ENDS 
SLEUl 
SLEU2 




2063a 
2063a 
2100 
2101 


1403b 1631a 1660a 


1753a 


2033b 





SAMPL 








LDR 1 02 


78173 


07/13/78 


14: 58: 05 


PAGE 2 




SEXIT 


SLOCA 
SLOCB 
EXIT 


2103 
2104 
2123a 


1402c 











® 

C LOfiD FL 



SRCW 



22332 



SRCHP 
SRCHR 
SRWDP 
SRWDR 

BUFFERS 



5441b 
5442a 
5551b 
5552a 
40060 



4256a 
LFT/DSPS - 



424 3 TOrrW. FL - 6275B, 



Figure 9-1. Example of a load map 
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10. Octal starting address of the block 

11. Octal word length of the block 

12. Date the object module was generated 

13. Operating system revision date at the time the object module 
was generated 

14. Name and revision level of the processor that generated the 
object module 

15. Revision date of the processor that generated the object 
module 

16. Comment (if any) from CAL COMMENT pseudo included in the load 
module 

17. Name of program block referenced 

18. Entry points in the program block 

19. Word address, parcel address, or value of each entry point 

20. Absolute parcel addresses of references to each entry point. 
Eight references are listed per line; some entry points have 
no references. 

21. Size of loaded binary, amount of memory used for I/O buffers, 
amount of memory used for LFTs and DSPs, and total amount of 
memory used. Total is the minimum amount of memory needed 
for the program. 



SELECTIVE LOAD 

If the I keyword is present on the LDR control statement, one or more 
INCLUDE and/or EXCLUDE directives are examined in the specified 
dataset. 
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Formats : 



INCLUDE 


rSDN= 


=sdn, 


FN 


=/n 


,wyD^md-^i 


:md2i . 


• . imd^Q, 




EXCLUDE, 


rSDN= 


=sdn, 


FN: 


=/n 


rMOD=md;j^S 


Wif 2 s • • 


. tmdgQ. 



Parameters are in keyword form. 

SDH=6dn Name of dataset containing modules to be selectively 

loaded. If SDN is specified without a value, the first 
dataset specified on the DN parameter of the LDR 
statement is the default. If the SDN parameter is 
omitted, an error message results, and the directive is 
skipped; the load does not abort. The SDN and FN 
parameters must refer to the same dataset. 

FN=/n File number of the specified dataset. A number from 
through 7. fn refers to the file by its numerical 
position in SDN or in the DN parameter of the LDR 
statement . 

For example, if DN=D1:D1:D2, the first file of Dl has an 
fn of 0, and the second file of Dl has an fn value 
of 1. If FN is specified without a value, the default 
is 0. If FN is omitted, the whole of sdn is searched 
for the correct module; a message is issued for a 
complete sdn search. The SDN and FN parameters must 
refer to the same dataset. 

To load a module from the first file of Dl, the 
directive may include the parameter FN=0; however, if FN 
is specified without a value, the default is to load a 
module from the first file. 

MOD=772<i Module name or entry point to a module to be included or 
excluded from the load. Up to 50 modules can be 
specified; the modules must be separated by colons. If 
the MOD parameter is omitted, an error message results, 
and the directive is skipped. 

Exanple: Given the LDR statement 

LDR,DN=D1:D1:D2,... 
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A directive to load a module from the second file of dataset Dl would 
include the following directive in the next file of $IN: 

INCLUDE, SDN=D1,FN=1,M0D=. . . . 
Selective load messages are never suppressed. 



RELOCATABLE OVERLAYS 

When a binary module is defined as a relocatable overlay, the loader 
can generate an image of the module that has been only partially 
relocated. The image of the binary module contains sufficient 
information for a user program to relocate all address references 
within the module program block according to the actual address at 
which the user program determines that the module should be executed. 

The relocatable overlay is useful because program modules are 
generated in such a way that a common memory pool can execute the 
overlay and also any of several overlays can execute at any address 
within the pool. 



GENERATION OF RELOCATABLE OVERLAYS 

The CAL assembler defines a module as a relocatable overlay at 
assembly time with the MODULE pseudo-op. 

Format : 



Location 


Result 


Operand 


ignored 


MODULE 


type 



Parameters: 

type A keyword parameter identifying the type of module being 

defined. RELOCOVL is the only type currently available. 

When the relocatable overlay is defined by the assembler, COS sets a 
special flag in the Program Descriptor Table (PDT) for use by the 
relocatable loader. 
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The loader, recognizing that the current module being loaded is a 
relocatable overlay, perforins limited relocation of the address 
references in the module. That is, all references to labeled COMMOm 
blocks and all references to entry points defined within other modules 
are adjusted according to the address at which the other module 
resides in the memory image being constructed. References to blank 
COMMON are illegal. It is also illegal for any other module to make 
any reference to any entry point which is defined to be within the 
relocatable overlay module. References from within the module to 
addresses within the module are not adjusted at this time. Instead, a 
copy of the necessary Block Relocation Table (BRT) entries is included 
in the memory image of the module. All BRT entries not needed for 
satisfying internal references are deleted. 

The absolute memory image of the program constructed by the loader 
will contain the loaded programs, including all relocatable overlay 
modules. 

The relocatable overlays are physically located at the end of the 
memory image; all nonrelocatable overlay modules are loaded 
contiguously in the order in which they are encountered. Relocatable 
overlay modules can appear at any point in the load sequence and can 
be contained in libraries. The loader moves modules in memory as 
required to order the relocatable overlays at the end of the image. 
This placement of the overlays makes it possible for a user program to 
locate the images of each overlay and to copy the overlays to mass 
storage, if it is desired, in order to make the memory space used by 
the overlay images available for use by the program.) 



MEMORY LAYOUT WHEN RELOCATABLE OVERLAYS EXIST 

When the loader has detected the existence of one or more relocatable 
overlays, memory is laid out in the following manner. 

1. All nonrelocatable modules, in the order they were encountered 
on load datasets or in libraries 

2. Labeled COMMON blocks interspersed among the nonrelocatable 
modules so that a labeled COMMON block precedes the absolute 
image of the first block encountered which defines the block 

3. All labeled COMMON blocks which are first defined within a 
relocatable overlay module and which are not defined within 
any other type of module 

4. The images of all relocatable overlays in the order in which 
they are encountered on load datasets or in libraries 



Part 2 
SR-0011 9-14 J-01 



5. Unsatified external (USX) program which is the loader's 
internal program for processing unsatisfied external references 

6, Blank COMMON if defined by any program module 

Note that the placement of USX and blank COMMON can defeat the purpose 
of relocatable overlays, since the overlay images must remain 
reserved. With proper care, the program can use the space occupied by 
the overlay images for internal tables and other data with 
nonallocated space. 



MEMORY LAYOUT OF A RELOCATABLE OVERLAY IMAGE 

When the loader completes constructing the image of the complete 
program being loaded, the relocatable overlay portions have a 
different structure than do the nonrelocatable overlay portions. 
Normal modules are loaded as an absolute image with all loader-related 
tables removed. All address references, both internal to the module 
and to other modules, are adjusted so that the code executes 
correctly. If the C parameter is specified when the loader is called 
into execution, individual modules may begin immediately after the 
previous module, or they may begin at the next 16-word (decimal) 
boundary. 

Because relocatable overlay modules are expected by the loader to be 
moved to a different address for execution, the C specification has no 
meaning to a relocatable overlay module, and the first and subsequent 
such modules begin immediately after the last word of the previous 
module. 

Relocatable overlay module images also contain loader-relocated 
tables. These tables are required so that the user program can adjust 
address references within a relocatable overlay when it has determined 
the address at which the overlay will execute. The tables are: 

• Program Description Table (PDT) 

• Text Table (TXT) 

• Block Relocation Table (BRT) 

The PDT contains information regarding the number of entry points 
defined and the number of blocks and external references. The TXT 
contains a count of the words in the actual image of the code, 
followed by the semi- absolute image of the code. The BRT contains 
information necessary for adjusting address references within the 
module. If the user program wants to write the overlays to mass 
storage, the information in the PDT can be used to construct a 
directory or similar table for locating specific overlays or entry 
points, and then can be discarded. TXT and BRT must be retained in 
the mass storage copy for future relocation of address references. 
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ADDRESS RELOCATION 

When a relocatable overlay has been loaded into the desired execution 
area, the BRT information must be used to locate all address 
references within the overlay. Information in the BRT includes a 
header with a word count and a number of words containing two 
relocation specifiers. Some words may contain only one specifier 
which must be in the left position because of the way in which the 
loader gathers references for the image. 

The format of the header follows: 



28 



63 



15 


WG 


//////////////////////////// 



Field 



WQ 



Bits 

0-3 

4-27 



Description 

Table type? 15-block relocation table. 

Number of words in the table, including the header 



There are Wc-X words of relocation specifiers. Each relocation 
specifier word contains two 32-bit values, the format of which is: 







8 



32 



63 



///// 


^ 


qwa 


////////////////////////////////I 



Field 



Bits 



c^a 



8-31 



Description 

Relocation mode: 

Reference requires a word address value 

1 Reference requires a parcel address value 

Quarter word address; indicates the parcel 
address of a field relative to the beginning of 
the overlay code image which must be modified. 

It consists of a 22-bit word address and a 2-bit 
field specifying the parcel within the word. 
Parcels are located within words as follows: 
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Field Bits 



Descript: 


ion 












Parcel 


Word 


Addr 




Parcel 


Location 





0-1 

***** _ 

** * 


















1 
2 
3 


**** 
** 








***** 
** 






***** 



** 



Relocation is 22-bits wide, and occurs across a 
word boundary if the parcel number is 0. 
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OVERLAY LOADING 10 



INTRODUCTION 

Very large programs may not fit in the available user memory space or 
may not use large portions of memory while other parts of the program 
are in execution. For such programs, the COS relocatable loader 
includes the ability to define and generate overlays — separate 
modules that the user creates and then calls and executes as necessary, 

Two types of overlays are available to the user, classified as either 
Type 1 or Type 2 depending on the directives used. Type 1 overlays 
are generated by using the generation directives ROOT, POVL, and 
SOVL, Two levels of overlays in addition to the root overlay are 
allowed with calls to a maximum of 999 adjacent overlays. Type 2 
overlays are generated by using the generation directive OVLL. Ten 
levels of overlays in addition to the root overlay are allowed with 
calls to a maximum of 63 adjacent overlays. 

The overlay loader can also generate a partially relocated module. 
This module is referred to as a relocatable overlay. It is described 
in part 2, section 9. 

The overlay structure, rules for overlay generation and overlay calls 
for both types are described in this section. The control statements 
used to generate the overlay and the directives common to both types 
of overlays are described first. Specific rules for generation of 
Type 1 and Type 2 overlays are described separately in the following 
subsections. 



OVERLAY GENERATION 

Overlay generation consists of a load operation in which the loader 
performs relocatable loading and writes the resulting binary image to 
disk. One named absolute binary record is written per root and each 
overlay. 

If the LDR control statement (part 2, section 9) has the parameter 
OVL=dir», the loader finds the overlay generation directives on the 
named dataset, dir. If no dataset is given (that is, OVL) , then the 
loader reads overlay generation directives from $IN. 
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The format of the control statement isi 



LDR, . • . ,OVL-dir», .... 



OVERLAY DIRECTIVES 

An overlay directive consists of a keyword and a parameter. A blank, 
comma, or open parenthesis must separate the keyword from the 
parameter. A period, closed parenthesis, or two consecutive blanks 
serve as the terminator. A caret ( ) at the end of the directive line 
indicates that the next line is a continuation of the current 
directive. The caret cannot be preceded by a blank; it must immediately 
follow the last character of the line. 



FILE directive 

The FILE directive indicates the dataset, dn, containing the routines 
to be loaded. This directive's function is similar to that of the DN 
parameter on the LDR control statement. It is generally the first 
directive on the directives dataset but may appear at any time and as 
often as necessary thereafter. If no FILE directive appears, the 
loading proceeds from the dataset specified on the DN parameter of the 
LDR control statement (see part 2, section 9). If that, too, has been 
omitted, loading initially occurs from $BLD. This directive is common 
to both overlay types. 



Format; 



FlLE,dn. 



OVLDN directive 

The function of this directive is similar to that of the AB parameter on 
the LDR control statement. This directive names the dataset, dn, on 
which overlays are written. The dn parameter must be present. If no 
OVLDN directive is present, the default overlay binary dataset ($OBD) is 
assigned. All overlays generated following an OVLDN directive reside as 
separate binary records on dataset dn. OVLDN directives may appear as 
often as desired. This directive is common to both overlay types. 
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Format: 



OVLDN,^n 



SBCA directive 

The SBCA directive sets the blank common starting address to the 
specified address. This directive allows the user to place blank common 
after all load modules in the current overlay structure. The address 
specified must be larger than any address used in the overlay 
structure. This directive must appear before any overlay generation 
directive, such as ROOT or OVLL. 



Format: 



SBCh, address , 



where address is the octal address assigned to blank common. 



TYPE 1 OVERLAY STRUCTURE 

Each Type 1 overlay is identified by a pair of decimal numbers, each 
from through 999. There must be one and only one root overlay; its 
level numbers are (0,0), This root remains in memory throughout program 
execution. Primary overlays all have level numbers (n,0) where n is in 
the range 1 through 999. 

Primary overlays are called at various times by the root and are loaded 
at the same address immediately following the root. A secondary overlay 
is associated with a specific primary overlay. The secondary level 
numbers are {n,m), where n is the primary level, and m is in the 
range 1 through 999. All secondary overlays associated with a given 
primary (i.e., the same n) are loaded at the same address immediately 
following that primary. 

Only the root, one primary overlay, and one secondary overlay can be in 
memory at one time. 
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Figure 10-1 is a diagram of a sample Type 1 overlay loading. The 
primary and secondary overlays are shown in time sequence. The sequence 
of generation does not imply that the programs are loaded into memory in 
the same sequence or that they remain in memory for a set period of time 
when they are executed. 

All external references must be directed toward an overlay nearer to the 
root. For example, overlay (1,0) may contain references to the root 
(0,0) but not to overlay (1,1). Overlay (1,1) may contain references to 
both (1,0) and (0,0). 

The loader places named common prior to the routine that first 
references it. All named common references must be directed toward a 
lower level routine. The lowest level routine with a named common block 
must contain data statements for that block. 

For example, in figure 10-1, 

MAIN can reference named common A only 

SUBl and SUB2 can reference named common A and B only 

TEST can reference named common A, B, and C 

The loader allocates blank common immediately after the first overlay in 
which it is declared. If blank common is declared in the root overlay 
(0,0), it is allocated at the highest address of the root overlay and is 
accessible to all overlays. If blank common is first declared in 
primary overlay (1,0) and not declared in the root (0,0), then it is 
accessible only to the (1,^) overlays. Allocation and placement of 
blank common may also be manipulated by the user through the SBCA 
director. 

JCHLM is set to the highest address of the root overlay prior to 
loading. If a subsequent overlay module requires additional memory, JCHL 
is reset to the highest address of that module 



Type 1 overlay generation directives 

The overlay generation directives define the structure of the overlay. 
Included in this class are the ROOT, POVL, and SOVL directives. 



ROOT directive - This directive defines programs, subroutines, and/ or 
entry points comprising the load from dn» For programs written in CAL, 
list each entry referenced. FORTRAN programs need the program name 
only. All members for this directive reside on the same dataset, drii as 
defined by the FILE directive. 
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JOB COMMUNICATION 
BLOCK 



200< 



NAMED COMMON A 
PROGRAM MAIN 



NAMED COMMON B 
SUBROUTINE SUBl 



SUBROUTINE SUB2 



BLANK COMMON 



IK 



ROOT (0,0) 



NAMED COMMON C f 

PRIMARY 

(1,0) 
PROGRAM TEST I 



PROGRAM 
NEWl 



"^ 



JCHLM 



SECONDARY 



PROGRAM 
NEW2 

(1,2) 






PROGRAM 
ALPHA 

SUBROUTINE 
BETA . 



PROGRAM 
DELTA 

(2,1) 






(5,1) 



time 



(5,0) 



(5,2) 



(5,3) 



(3,0) 



(2,0) 



(2,3) 



^^lii unused 



Figure 10-1. Example of Type 1 overlay loading 
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Format: 



ROOT, member-^ ,member2 ,member^ 



POVL directive - This directive causes relocatable loading of the named 
blocks to the primary overlay with the name plevel :000. The size of the 
root determines the base location. All members for this directive 
reside on the same dataset, dn . The first member in the list is the one 
that receives control when the overlay is loaded. For programs written 
in CAL, the first entry point of the first routine receives control. 

Format: 



POVL, plevel , memberi ,member2 , • - . ,member. 



n' 



where plevel is between 1 and 999. 



SOVL directive - This directive causes relocatable loading of the named 
blocks to the secondary overlay with the name plevel xslev el , The length 
of POVL (pZ-eyeZ:000) determines the base location. All members for this 
directive reside on the same dataset, dn. The first member in the list 
is the one that receives control when the overlay is loaded. For 
programs written in CAL, the first entry point of the first routine 
receives control. 



Format: 



SOVL, slevel ,membev\,membeT2i • • • tmembev. 



n' 



where slevel is between 1 and 999. 
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Rules for Type 1 overlay generation 

1. Overlay members are loaded from datasets named in FILE 
directives. Members are searched for in the most recently 
mentioned dataset only. In the absence of a FILE directive, 
members are loaded from the dataset specified on the LDR control 
statement. If that is also omitted, loading will initially occur 
from $BLD. Currently, the relocatable modules of all members for 
any overlay level must reside on the same file. 

2. The overlays are generated in the order of the directives. 

3. There must be one and only one root. 

4. Level hierarchy must be maintained. The ROOT overlay must be 
generated first; hence the ROOT directives appear first. 
Following the ROOT generation, a primary overlay (POVL) is 
generated. No limitation is placed on which primary overlay 
number {ptevet) is generated; however, all secondary overlays 
(SOVL) associated with the plevet must follow. The secondary 
overlay slevels may be generated in any order following their 
respective primary level. 

5. An end-of-file in the directives file ends the input of overlay 
directives; hence overlay generation. 

6. Any directive other than FILE, OVLDN, SBCA, ROOT, POVL, or SOVL 
causes a fatal error. 

7. The list of members may be continued to another line by using a 
caret (a) immediately following the last character at the end of 
the directive line (that is, no blanks). The A does not replace 
a separator and must not appear within a member name. 

8. Any number of lines may be used to name the members of an overlay. 



Example of Type 1 overlay generation directives 

In the following example, 

DSETl contains routines THETA, TEST, GAMMA, SUBl , MAIN, SUB 2. 

DSET2 contains routines NEW2, ALPHA, OVER, NEWl, DELTA, EPSILON, 

SIGMA, BETA. 

Format of the control statement that initializes overlay generation: 
LDR, . . . , OVL=OVLIN, 
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Dataset OVLIN contains the following directives: 



FILE , DSETl . 
OVLDN,LEV00. 



R00T,MAIN,SUB1 
,SUB2. 

P0VL,1,TEST. 



FILE,DSET2. 
S0VL,1,NEW1. 

0VLDN,LEV12. 

SOVL,2,NEW2. 



Loader selectively loads from dataset DSETl. 

The following overlay modules are written to the 
dataset LEVOO. 

The absolute binary of MAIN,SUB1,SUB2 is 
written as the first record on dataset LEVOO. 

The binary of TEST is named 001:000 and is 
binary record 2 on dataset LEVOO. 

Loader selectively loads from dataset DSET2. 

The binary of NEWl is named 001:001 and is 
binary record 3 on dataset LEVOO. 

The subsequent overlay modules are written to 
the dataset LEV12. 

The binary of NEW2 is named 001:002 and is 
binary record 1 on dataset LEV12. 



POVL, 2, ALPHA, BETA. The binary of ALPHA, BETA is named 002:000 and is 

record 2 on dataset LEV12* 



<eof> 



End of overlay load sequence 



Execution of Type 1 overlays 

A control statement call of the dataset containing the ROOT overlay 
initiates its loading and execution. If no OVLDN directives are used 
before generating the ROOT, the dataset $OBD will contain the ROOT 
overlay. 

The following sequence executes the root overlay after generation: 

LDR,. ..,OVL=dip, 

$OBD. 
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During overlay generation the members are loaded from the FILE dataset 
in the order they appear on the dataset, regardless of their order of 
appearance in the members list. The entry for POVL and SOVL overlays is 
defined by the first member listed on the generation directive. Control 
is transferred to this address after loading by the $OVERLAY routine 
during program execution. The ROOT entry may be named using the T 
parameter on the LDR control statement (see part 2, section 9). 



Type 1 overlay calls 

The user calls for the loading of overlays from within the program, and 
the method by which they are called depends on the program language in 
use (FORTRAN or CAL) . OVERLAY is a subroutine of the root overlay and 
is loaded into memory with the root. 



FORTRAN Language Call 

A FORTRAN program calls for the loading of overlays as follows: 



CALL OVERLAY inljdn,leveti,level2,r) 



n 

L 

dn 

level-^ 

p 



Number of characters in the name 

Left-adjusted; zero filled 

Name of the dataset on which this overlay resides 

Primary level number of the overlay 

Secondary level number of the overlay 

An optional recall parameter. If the user wishes to 
re-execute an overlay without reloading it, 6LRECALL may 
be entered. If it is not currently loaded, it will be 
loaded . 
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CAL Language Call 

A sample call sequence from a CAL program is as follows: 



Locatron 


Result 


Operand 




EXT 


OVERLAY 




SI 

S2 

S3 

W. OVERLAY- 1,0 

W.OVERLAY-2,0 

W.OVERLAY-3,0 

R 


OVLDN 

PLEV 

SLEV 

SI 

S2 

S3 
OVERLAY 


3VLDN 

'LEV 

>LEV 


CON 
CON 
CON 


A'LEV12'L 

2 





where OVLDN is the address of the dataset name, PLEV is the address of 

the primary level, and SLEV is the address of the secondary level. If 

recall is desired, the address of the literal RECALL is transmitted to 
W. OVERLAY- 4. 

Example: 



Location 



Result 



Operand 



W.OVERLAY-4,0 



=' RECALL' L 
Sk 



For both FORTRAN and CAL language calls, during execution of the 
ROOT(0,0) program MAIN, the statement 

CALL OVERLAY (5LLEV12, 2,0) or the above CAL sample call 

causes OVERLAY to search dataset LEV12 for the absolute binary named 
002:000. OVERLAY positions the dataset LEV12 to the location of the 
absolute binary named 002:000 using information supplied by the loader, 
loads the overlay, and transfers control to the first member specified 
on the POVL or SOVL directive. After execution of the overlay, control 
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returns to the statement in MAIN immediately following the CALL 
statement. Following the load, dataset LEV12 is positioned immediately 
after the end of record for the overlay (2,0) . If overlay (2,0) is not 
on dataset LEV12, a fatal error results. 

Placing a call for a secondary overlay for which the corresponding 
primary overlay is not already loaded causes OVERLAY to load both 
overlays. Control transfers to the secondary after both overlays are in 
memory. A fatal error results if the primary and secondary overlays are 
not both on the named ovldn, if the overlays reside on different 
datasets, the user must place separate calls to load the overlays in the 
correct order . 



Log of Type 1 overlay generation 

When MAP is specified on the LDR control statement, a listing is 
generated that describes where each module is loaded and what entry 
points and external symbols were used for loading. This listing is an 
overlay load map and is similar to the map of a non-overlay load (part 
2, section 9). A log of the directives used follows the map of the last 
overlay generated, if overlay loading aborts, the directives are not 
listed. 



TYPE 2 OVERLAY STRUCTURE 

A Type 2 overlay is identified by a pair of decimal numbers that 
indicate the overlay level and the number of the overlay within that 
level. The overlay notation is of the form {level,numhev) where the 
value of level is in the range 1 through 10 and the value of numheT is 
in the range 1 through 63. Only one root overlay exists; its level 
number is 0. The root overlay remains in memory during the entire 
program execution and may call only level one overlays. 

Level one overlays are called at various times by the root overlay; each 
call loads the named overlay at the same address, which is immediately 
following the location of the root. The first level overlay must be 
called by the root; each upper level overlay may be called by the 
associated overlay at the adjacent lower level. A hierarchy exists 
among overlay levels; an upper level overlay is subordinate to the 
proximate lower level overlay. An upper level overlay associated with 
overlay (2,1) might be (3,2), (3,3) or (3,4). 
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JOB COMMUNICATION 
BLOCK 



200c 



NAMED COMMON A 
PROGRAM MAIN 



NAMED COMMON B 
SUBROUTINE SUB1 



LEVEL (0) 
(ROOT) 



SUBROUTINE SUB2 



o 

E 
E 



BLANK COMMON 



NAMED COMMON C | 
LEVEL 1 

(1,1) 
PROGRAM TEST 



PROGRAM 
NEWl 



LEVEL 2 






PROGRAM 
ALPHA 



JCHLM 
A— 



LEVEL 3 



PROGRAM 
BETA 
(3,2) 



PROGRAM 
NEW2 

(2,2) 



(1,5) 



(2,1) 



lllllll unused iili||| 



(1-^^ 



(1,2) 



(2,1) 



(2,4) 



(3,1) 



(4,1) 



(1,4) 



(2,1) 



(4,2) 



isli unused liiiii 



time 



Figure 10-2 . Example of Type 2 overlay loading 
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An overlay can call into memory any overlay in the next higher level; it 
cannot call an overlay more than one level above it in the hierarchy. 
For example, overlay (2,1) can call (3,1) through (3,63), but it cannot 
call (4,1). Each call for an overlay loads the named overlay at the 
same address location, which immediately follows the location of the 
calling overlay. Only the root and one overlay at each level can be in 
memory concurrently. 

All external references must be directed toward an overlay nearer the 
root overlay. Overlay (1,1) may contain references to the root overlay 
but not to overlay (1,2) or overlay (2,1). The (2,1) overlay may 
reference externals in both the (1,1) overlay and the root overlay. 

The loader places named common blocks prior to the routine that first 
references it. All named common references must be directed toward a 
lower level routine (toward the root overlay). If blank common is 
declared in the root overlay, it is allocated at the highest address of 
the root and is accessible to all overlays. If blank common is declared 
first in a level one overlay, for example, and is not declared in the 
root overlay, it is accessible only to level one and upper level 
overlays. 

JCHLM is set to the highest address of the root overlay prior to 
loading. If a subsequent overlay module requires additional memory, 
JCHLM is reset to the highest address of that module. 

Figure 10-2 shows a sample Type 2 overlay loading diagram. The overlays 
are shown in time sequence. The sequence of generation does not imply 
that the programs are loaded into memory in the same sequence or that 
they remain in memory for a set period of time when they are executed. 



Type 2 overlay generation directive 

The Type 2 overlay directive defines the structure of the overlay within 
the directive format. 



OVLL directive - This directive causes relocatable loading of the named 
blocks of an overlay. The size of the lower level overlays in the group 
determines the base location. All members for this directive reside on 
the same dataset, dn, specified by the FILE directive. The first member 
in the list is the one that receives control when the overlay is 
loaded. For programs written in CAL, the first entry point of the first 
routine receives control. 
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Format: 



OVLL, level fYiimber /nembev-^ jmemhev2 , , . . ,memheTy^ 



level Level number of the overlay (1 < level <_ ^^^ • 

If level is 0, the root phase is generated and 
the nwnher must be omitted. 

number Number of the overlay within the level 
(1 <_ number £ 63) . 

member Module names for the individual overlays 



Rules for Type 2 overlay generation 

1. Overlay members are loaded from datasets named in FILE 
directives. Members are searched for in the most recently 
mentioned dataset only. In the absence of a FILE directive, 
members are loaded from the dataset specified on the LDR control 
statement. If that is also omitted, loading initially occurs 
from $BLD. 

2. The overlays are generated in the order of the directives. 

3. There must be one and only one root per dataset. 

4. Level hierarchy must be mai tained. The root overlay must be 
generated first. Following the root generation, a first level 
overlay is generated. No limitation is placed on which overlay 
number is generated; however, all overlays associated with that 
first level overlay must follow. The overlays may be generated 
in any order; the same restrictions apply for all levels of 
overlays (1 through 10) . 

5. An end-of-file ends the input of overlay directives. 

6. Any directive other than FILE, OVLDN, SBCA or OVLL causes a fatal 
error . 
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7. The list of members can be continued to another line by using a 
caret (A) immediately following the last character at the end of 
the directive line (that is, no blanks). The A does not replace 
a separator and must not appear within a member name. 

8. Any number of lines can be used to name the members of an overlay. 



Example of Type 2 overlay generation directives 

In the following example, 

DSETl contains routines THETA, TEST, GAMMA, SUBl, MAIN, SUB2. 

DSET2 contains routines NEW2, ALPHA, OVER, NEWl, DELTA, EPSILON, 

SIGMA, BETA. 

Format of the control statement that initializes overlay generation: 
LDR,.. .,OVL=OVLIN, .. . 



Dataset OVLIN contains the following directives: 



FILE , DSETl . 
OVLDN,LEV00. 



OVLL,0,MAIN,SUB1, 
SUB2. 



OVLL, 1,1, TEST. 

FILE,DSET2. 
OVLL, 2,1, NEWl. 

0VLDN,LEV12. 

0VLL,2,2,NEW2. 

OVLL, 3,1, ALPHA. 



Loader selectively loads from dataset DSETl. 

The following overlay modules are written to 
the dataset LEVOO. 

The absolute binary of MAIN, SUBl, SUB2 

is named and is the first record on dataset 

LEVOO . 

The binary of TEST is named 1 and is binary 
record 2 on dataset LEVOO. 

Loader selectively loads from dataset DSET2, 

The binary of NEWl is named 10 Is and is 
binary record 3 on dataset LEVOO. 

The subsequent overlay modules are written to 
the dataset IiEV12. 

The binary of NEW2 is named 2018 and is 
binary record 1 on dataset LEV12. 

The binary of ALPHA is named 102018 and is 
binary record 2 on dataset LEV12. 
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OVLL,3,2,BETA. The binary of BETA is named 202018 and is 

binary record 3 on dataset LEVI 2. 



<eof> End of overlay load sequence. 



Execution of Type 2 overlays 

A control statement call of the dataset containing the root overlay 
initiates its loading and execution. If no OVLDN directives are used 
before generating the root, the dataset $OBD will contain the root 
overlay. All overlays reside on the datasets specified on the overlay 
directives. The entry for higher level overlays is defined by the first 
member listed on the generation directive. Control is transferred to 
this address after loading by the $OVERLAY routine during program 
execution. The root entry may be named using the T parameter on the LDR 
control statement (see part 2, section 9). 

The following sequence executes the root overlay after generation: 

LDR , . . . , OVL= dir, .... 
$OBD. 

When the program is to be executed, the root overlay is brought into 
memory as a result of a control statement call in the job deck. 
Thereafter, additional overlays are called into memory by the executing 
program. Overlay loading allows any overlay to call for the loading of 
an adjacent upper level overlay. 



Type 2 overlay calls 

The user calls for the loading of Type 2 overlays from within the 
program, and the method by which they are called depends on the program 
language in use (FORTRAN or CAL) . OVERLAY is a subroutine of the root 
overlay and is loaded into memory with the root. 



FORTRAN Language Call 

A FORTRAN program calls for the loading of Type 2 overlays as follows: 



CALL OVERLAY {nidn, level ,nvimber,r) 
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I 



n Number of characters in the name 

L Left-adjusted, zero filled 

dn Name of the dataset on which this overlay resides 

level Level number of the overlay 

number Number of the overlay within the level 

T Optional recall parameter. If the user wishes to 

re-execute an overlay without reloading it, 6LRECALL may 
be entered. If it is not currently loaded, it will be 
loaded . 



CAL Language Call 









Location 


Result 


Operand 




EXT 


OVERLAY 




SI 

S2 

S3 

W.OVERLAY-1 ,0 

W.0VERLAY-2,0 

W.0VERLAY-3,0 

R 


OVLDN 

LEVEL 

NUMBER 

SI 

S2 

S3 
OVERLAY 


OVLDN 
LEVEL 
NUMBER 


CON 
CON 
CON 


A'LEV12'L 

1 

2 



where OVLDN is the address of the dataset name, LEVEL is the address of 
the overlay level, and NUMBER is the address of the number within the 
level. If recall is desired, the address of the literal RECALL is 
transmitted to W.OVERLAY-4. 
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Example: 



Locat i on 


Result 


Operand 




W.OVERLAY-4,0 


=' RECALL 'L 



For both FORTRAN and CAL language calls, during execution of the ROOT 
program MAIN, the statement 

CALL OVERLAY (5LLEV12,1, 2) , or above CAL sample call 

causes OVERLAY to search dataset LEV12 for the absolute binary named 2. 
OVERLAY positions the dataset LEV12 to the location of the absolute 
binary named 2 using information supplied by the loader, loads the 
overlay, and transfers control to the first member specified on the OVLL 
directive. After execution of the overlay, control returns to the 
statement in MAIN immediately following the CALL statement. Following 
the load, dataset LEV12 is positioned immediately after the end of 
record for the overlay 2. If overlay 2 is not on dataset I£V12, a fatal 
error results. 



Log of Type 2 overlay generation 

When MAP is specified on the LDR control statement, a listing is 
obtained that describes where each module is loaded and what entry 
points and external symbols were used for loading. This listing is an 
overlay load map and is similar to the map of a non-overlay load (part 
2, section 9). A log of the directives used will follow the map of the 
last overlay generated. If overlay loading aborts, the directives are 
not listed. 



SR-0011 



Part 2 
10-18 



BUILD 11 



INTRODUCTION 

BUILD is an operating system utility program for generating and 
maintaining library datasets. A Hhravy dataset is a dataset 
containing a program file followed by a directory file. Library 
datasets are designed primarily to provide the loader with a means of 
rapidly locating and accessing program modules. The program file is 
composed of loader tables for one or more absolute or relocatable 
program modules. The directory file contains an entry for each 
program. The entry contains the name of the program module; the 
relative location of the program module in the dataset; and block names, 
entry names, and external names. 

The BUILD program constructs a library from one or more input datasets 
named by the user when BUILD is called. A library dataset created by a 
BUILD run may be used as input to a subsequent BUILD run. Through BUILD 
directives, the user designates the program modules to be copied from 
the input datasets to the new library and the order in which they are to 
be placed in the library. However, no directives or control statement 
parameters are needed for the most frequent application of BUILD, which 
is to add new binaries from $BLD to an existing library of binary 
programs, replacing the old binaries where necessary. 



PROGRAM MODULE NAMES 

BUILD directives refer to program modules by their names as given in the 
directory or, if the directory is missing or is unreadable, by the names 
given in the program modules. 



PROGRAM MODULE GROUPS 

In the COPY and OMIT directives, program modules whose names contain one 
or more identical groups of characters may be specified together, with 
the variable parts of each name relaced by one or more hyphens. For 
example, XYZ- represents all names beginning with XYZ, including XYZ 
itself. In the extreme case, a name consisting of only a hyphen 
represents all possible names. 
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In addition, up to eight asterisks may be used anywhere in a name as 
wild characters matching any character other than a blank. For 
example, GE* specifies a group of modules having three-character names 
including GET and GEM but not GE or GEMS. 



PROGRAM MODULE RANGES 

In order to facilitate the copying of large numbers of contiguous 
program modules, the COPY directive allows a range specifier to be 
used instead of a single name or group specifier. The range specifier 
has the general form: 



{first, last) 



which means: skip to the first module and then copy all modules from 
that first one up to and including the last module. 



FILE OUTPUT SEQUENCE 

If the SORT parameter appears in the BUILD control statement, all 
modules are copied alphabetically according to their new names. In 
the absence of a SORT parameter, modules are written in the order in 
which they are read originally from the input datasets. 

The order of the entries in the directory is always the same as the 
order of the modules themselves. 



FILE SEARCHING METHOD 

The user need not be aware of the order of modules in the input 
dataset unless (1) there are two or more modules with the same name or 
(2) a range is specified in a COPY directive. 

If two or more modules with the same name are in the input datasets, 
the last of the modules read is the one that survives, unless the user 
specifically omits that last module while its original dataset is the 
currently active input dataset. 
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The concept of cuvrent position in the input file is used to interpret 
range specifiers in which the first name is omitted as in ( , ) or 
(,). In such cases, the current position is defined to be either 
immediately after the last module copied or at the beginning of the 
dataset if no modules have yet been copied. 



BUILD CONTROL STATEMENT 



Format: 



BUILD , I =ddn , L=ldn , OBL=odn , B=bdn , NBL=ndn , SORT , NODIR , replace . 



Parameters are in keyword form. 

l=idn Name of dataset containing BUILD directives, if any. 

Directives may be included in the $IN dataset, or they may 
be submitted in a separate dataset. 

If the I parameter appears alone or is omitted, all 
directives are taken from the $IN dataset, starting at its 
current position and stopping when an end-of-file is read. 

If l=ddn, all directives are taken from the specified 
dataset, ddn, stopping when an end-of-file is read. 

If 1=0, no directives are read. The most common condition 
is to merge the modules from odn (the OBL dataset) with 
those from bdn (the B dataset) , replacing OBL modules with 
B modules whenever the names conflict, and to write the 
output to ndn (the NBL dataset). Note that the input 
dataset specified by the B parameter corresponds to the 
binary output from CAL and CFT, also designated by B. 

L=ldn Name of list output dataset. 

If the L keyword appears alone or is omitted, list output 
is written to $OUT. 

If L=ldn , list output is written to Idn, 

If L=0, no list output is written. 
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OBh=odn Name of the first input dataset, which is usually a 
previously created program library. 

If the OBL parameter is omitted or appears alone, the 
first dataset read is $OBL. 

If OBL=odn, the first dataset read is odn , 

If OBL=0r no old binary library exists. This is a 
creation run. 

B=bdn Name of the second input dataset, whose modules will be 

added to or will replace the modules in the first 
dataset. 

If the B parameter appears alone or is omitted, the 
second dataset read is $BLD. 

If B=bdn , the second dataset read is bdn , which is read 
to the first end-of-file. 



NBL =n(in 



If B=0, no modules are being added. This run edits an 
old library. 

BUILD stops at end-of-file; bdn is not required. 

Name of the output dataset, which is usually considered 
to be a new program library. 



If the NBL parameter appears alone or is omitted, output 
is written to $NBL. 

If NBL=ndn, output is written to ndn . 

If NBL=0, no output is written. This usage is intended 
for checking out BUILD directives. 

SORT Specifies that all modules are to be listed 

alphabetically according to their new names. The 
default is to list the modules in the order they were 
first read. 

NODIR Specifies that no directory is to be appended to the 
output dataset, resulting in an ordinary sequential 
dataset like $BLD. The default is to append the 
directory. 
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REPLACE Specifies that the output library is to contain modules in 
the same order as the old library. If omitted, the new 
library contains modules from the old library which were 
not replaced by modules from the input binary dataset, 
followed by modules from the input dataset. 

Any of the following errors causes BUILD to abort: 

• A module specified explicitly in a COPY or OMIT directive is 
not in the current input dataset. 

• A module specified explicitly in a COPY directive has already 
been selected for output. 

• Improper syntax is used in the BUILD control statement or in 
the directive dataset. 

• An unrecognized directive or control statement keyword is used. 

• A dataset name or module name is too long or contains illegal 
characters. 



BUILD DIRECTIVES 

BUILD is controlled through directives in a dataset defined by the I 
parameter on the BUILD control statement. A directive consists of a 
keyword and, if the keyword requires it, a list of dataset names or 
module names. When names are required, the keyword must be separated 
from the first name by a blank; subsequent names (if any) in the list 
are separated from each other by commas. Extra blanks are optional 
except within the keyword. 

A line can contain more than one directive; periods or semicolons are 
used to separate directives on the same line from each other. A 
directive cannot be continued from one directive line to the next. 

Examples of directives: 

OMIT ENCODE, DECODE 

COPY **CODE. 
Examples of multiple directives on one line: 

FROM OLDLIB; LIST; OMIT ENCODE, DECODE, XLATE 

FROM $BLD. LIST. 
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FROM DIRECTIVE 

A FROM directive may name a single dataset, which is thus established 
as the input dataset for succeeding COPY, OMIT, and LIST directives, 
or it may list several datasets that (except for the last dataset in 
the list) are to be copied in their entirety to the output dataset 
($NBL) . The last dataset in the list is established as the current 
input dataset, just as if it were specified alone in the FROM 
directive. If no COPY or OMIT directive follows, the last dataset is 
also copied in its entirety to the output dataset. 

An input dataset may be a library (with a directory) or an ordinary 
sequential dataset (such as $BLD) . BUILD always determines whether a 
directory is present at the end of the dataset and attempts to use it 
if it is there. A library dataset is treated as sequential if its 
directory file is unreadable for any reason. 



Format 



FROM dn -, ,dn 9 r • • • >dn 



n 



The following general rule allows the user to copy several datasets 
from one FROM directive or to omit COPY (which means "copy all") when 
it would be the only directive (except for OMIT directives) in the 
range of a particular FROM directive: 

If any dataset named on a FROM directive are not acted on by any 
LIST or COPY directive, then BUILD copies all of the modules 
belonging to that dataset. BUILD takes this action when it 
encounters the next FROM dataset name or the end of the directive 
file, whichever comes first. 

If there are two input datasets to be read as soon as BUILD begins to 
execute (that is, if neither OBL=0 nor B=0 is specified), the modules 
from these two datasets are treated as if they belong to a single 
dataset as far as the OMIT, COPY, and LIST directives are concerned. 
However, if either of them is named in a FROM directive, it is treated 
as a separate dataset and OMIT, COPY, and LIST directives apply only 
to whichever is the current input dataset. 
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OMIT DIRECTIVE 

The OMIT directive allows a user to specify that certain modules 
otherwise included in a group be omitted from the group on subsequent 
copy operations. An OMIT affects modules on the current input dataset 
only; its effect ends when a FROM directive is encountered. 



Format : 



OMIT fn-^,fn2,...,fn. 



n 



Each fn^ may be one of the following: 

• A single name, such as $AB@CDEF or CAB22 , by which binary 
records can be explicitly prevented from being copied 

• A group name, such as F$- or *AB**, by which binary records are 
prevented from being copied unless they are specified 
explicitly (i.e., singly) in a COPY directive (see AUDIT 
statement for description of * and -) 

If an fn parameter specifies a module not in the input dataset or a 
group of modules having no representatives in the input dataset, a 
diagnostic message is included in the list output and BUILD aborts. 



COPY DIRECTIVES 

COPY directives cause BUILD to select the specified modules for 
copying from current input dataset to the output dataset. The user 
may specify single modules, groups of modules, or ranges of modules to 
be copied. If the user specifies a module that is not in the current 
input dataset, a diagnostic message is included in the list output and 
BUILD aborts. 



Format: 



COPY /ni,/n2,...,/n^ 
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Each fn. may be either of the two forms that are valid in OMIT 
directives: 

• A single module name, by which modules are explicitly selected 
for copying, even if they belong to a group named in a previous 
OMIT directive 

• A group specifier, by which all the modules in the group are 
selected for copying unless they were specified either 
explicitly or implicitly in a previous OMIT directive 

In addition, two special forms are allowed for each fn-l in COPY 
directives: 

• A form to rename a single module whose old name is specified 
explicitly; for example, OLDNAME=NEWNAME . (The name is changed 
both in the output directory and in the PDT. ) 

• A form to copy an inclusive range, as in (FIRST, LAST) , by which 
all the modules in the range are selected for copying unless 
they were specified either explicitly or implicitly in a 
previous OMIT directive. 

These two forms are mutually exclusive. A module copied by being 
included in a range cannot at the same time be renamed. Nor can 
either form accept a hyphen or asterisk specifying a group of modules. 

Examples: 

BUG=ROACH Copies BUG, renaming it to ROACH 

(LOKI,THOR) Copies all modules from LOKI through THOR 

(THOTH,) Copies all modules from THOTH to the end of the 
input dataset 

(,ISIS) Copies all modules from the current dataset 
position through ISIS 

(,) Copies all modules from the current dataset 

position to the end of the input dataset 

The current dataset position is defined as the beginning of the input 
dataset if no modules have been selected for copying yet, or else as 
the beginning of the record immediately after the last module that has 
been selected for copying. 
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LIST DIRECTIVE 

The LIST directive tells BUILD to list the characteristics of the 
modules in the current input dataset. Its effect is immediate. 
(build's standard list output describes the contents of the output 
dataset and is produced at the end of the run so as not to interfere 
with output triggered by LIST directives.) 



Format: 




EXAMPLES 

The following are examples of various uses of the BUILD program: 

• Creating a new library dataset, using as input whatever binary 
modules have been written out to $BLD by CAL and/or CFT. 

Control statements: 

BUILD, OBL=0, 1=0. 

SAVE , DN=$NBL , PDN=MLIB . 



• Adding one or more modules to an already existing library 
dataset, again taking the input from $BLD. 

Control statements: 

ACCESS , DN=$OBL , PDN=MYLIB . 
BUILD, 1=0. 
SAVE,DN=$NBL,PDN=MYLIB. 



Any modules whose names were already in the directory of MYLIB 
are replaced by the new binaries from $BLD in the new edition 
of MYLIB that is created by BUILD and saved by the SAVE control 
statement. 
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• Merging several libraries. 

Control statements: 

ACCESS , DN=LIBONE , PDN=HERLIB . 

ACCESS , DN=LIBTWO , PDN=HISLIB . 

ACCESS , DN=ANOTHER , PDN= ITSLIB . 

ACCESS , DN=LASTONE , PDN=MYLIB . 

BUILD,I,OBL=0,B=0. 

SAVE , DN=$NBL , PDN=NEWLIB . 

Directives: 

FROM L I BTWO, ANOTHER, LI BONE, LASTONE 

The order of the dataset names in the FROM directives, not the 
order of the ACCESS control statements, determines the order of 
processing. If two datasets contain modules of the same name, 
the surviving module is the one in the dataset whose name 
occurs later in the FROM directive. (Any module could be 
renamed before input from a succeeding dataset is begun, in 
order to prevent it from being discarded.) 

• Deleting a program module from a library. 
Control statements: 

ACCESS , DN=$OBL , PDN=MYLIB . 

BUILD, B=0. 

SAVE , DN=$NBL , PDN=MyLIB . 

Directive: 

OMIT BADPROG 

• Extracting a program module from a library for input to the 
system loader, using the local dataset name $BLD as the 
intermediate file. 

Control statements : 

ACCESS,DN=XXX,PDN=MYLIB. 
BUILD,I,OBL=XXX,B=0,NBL=$BLD,NODIR. 

Directive: 

COPY RUNPROG 
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INTRODUCTION 



Included with the CRAY-1 Operating System is a set of macro 
instructions that provide the user with a means of communicating with 
COS. These macro instructions are available only when programming in 
the CAL assembler language and are processed by the assembler using 
macro definitions defined in the system text, $SYSTXT. The code 
generated by the macros represents a call to a system task or a 
system-provided subroutine, or it generates a table. 

The format for a macro instruction is: 



Location 


Result 


Operand 


loo 


name 


a2.''^2' " * ''^J'^i~^i'^2~^2' ' ' * '^k'^k 



loe 



Location field argument. Certain macros require an entry 
in this field. For other macros, toe is an optional 
symbolic program address. Macros that generate a table 
are assigned a word address; macros that generate 
executable code are assigned a parcel address. 



name Name of macro as given in system text 

a^ Actual argument string corresponding to positional 

parameter in prototype. Two consecutive commas indicate a 
null string. 






Keyword and actual argument; these entries can be in any 
order. A space or comma following the equal sign 
indicates a null string. 



Stacked items within braces signify that one and only one 
of the listed items must be entered. 



A parameter shown in all UPPERCASE letters must be coded literally as 
shown. A parameter presented in italics must be supplied with a value, a 
symbol, an expression, or a register designator as indicated in the text 
following the format for each macro. 
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A macro can be coded through column 72 of a line. It can be continued on 
the next line by placing a comma in column 1 of the next line and resuming 
the parameter list in column 2, with no intervening blanks at the end of 
the first line. 



NOTE 



Use the AO and SO registers as parameters with care. 
When a macro that includes AO or SO as a parameter is 
expanded, special syntax values are used rather than 
the value of the contents of AO or SO. 
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SYSTEM ACTION REQUEST MACROS 



The system action request macros are a subset of the system function 
requests. Each macro generates a function code that is a call to the 
operating system. The octal function value is stored in register SO; 
SI and S2 provide additional arguments for some requests. The 
function is enabled when the program exit instruction is executed. 
The contents of the registers used are not restored after the call is 
completed . 

See the COS EXEC/STP/CSP Internal Reference Manual, CRI publication 
SM-0040 for more information on system function codes. 

The system action request macros can be divided into five main 
classes: those involved in job control, those related to dataset 
management, those representing requests for time or date, those that 
are debugging aids, and miscellaneous. Any macro that generates 
executable code can have a label. 



JOB CONTROL 

Several system action request macros allow the user to set operating 
characteristics and control job processing. These include MEMORY, 
MESSAGE, CSECHO, MODE, SWITCH, JTIME, RECALL, DELAY, ABORT, SETRPV, 
ENDRPV, ROLL, ENDP, NORERUN, RERUN, lOAREA, and DUMP JOB. 
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MEMORY - REQUEST MEMORY 

The amount of memory assigned to the job may be determined or changed 
by the memory request. If the user area is expanded, the additional 
memory is set to an installation-defined value before control returns 
to the user. The job is aborted if filling the request would exceed 
the maximum allowable memory for the job. 



Format : 



Location 


Result 


Operand 




MEMORY 


address 



address A symbol or an A, S, or T register (except AO or SO) that 
contains the request word address 

The format of the word at location address is as follows: 

2 7 16 40 63 



M 


/ 


L 


/// 


T 


//// 


DEL 


WC 



Field Bits 



M 



Description 

Maximum memory flag. If set by the caller, the 
system returns in WC the maximum allowable 
amount of memory (in words) not including the 
Job Table Area (JTA) . No memory is allocated. 

Limit flag. The system sets this flag when the 
job has received the maximum allowable amount of 
memory . 

Total flag. If T is set, WC represents the 
total memory requested (excluding the JTA) 
rather than an increment or decrement. If T is 
specified, DEL is ignored. 



SR~0011 



Part 3 
2-2 



Field 



DEL 



Bits Description 

16-39 Deletion pointer. If the caller wants an 

increase in memory, DEL must equal 0. If the 
caller wants a decrease in memory, DEL must 
contain the address relative to the user's base 
address of the beginning of the area to be 
deleted. 



WC 



40-63 



Word count. Here, if T=0, the caller must 
supply the absolute number of words to be added 
to or deleted from the user area. If T=l, the 
caller must supply the total field length 
desired. If T=0 and WC=0, no action is taken 
other than to return the user's field length as 
described below. 



In the memory request word, L may be set by the 
system as described above. When WC and T equal 
0, the system sets WC to the current total 
number of words in the user's field length. The 
total number of words in the user's field length 
does not include the Job Table Area but does 
include the I/O buffers and tables. 



MESSAGE - ENTER MESSAGE IN LOGFILE 

The printable ASCII message at the location specified in the macro call 
is entered in the job and system logfile. The message must be 1-80 
characters terminated by a zero byte. A flag, too, indicates the 
destination for the message. 



Format : 



Location 


Result 


Operand 




MESSAGE 


address, toe, msgelass, override 



address A symbol or an A, S, or T register (except AO, SO, and S2) 
that contains the starting address of the ASCII message 
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too Destination for message. Can be any of the following: 

U User logfile only 

S System logfile only 

US User and system logfiles; default if toe is blank 

toe can be a symbol or an A, S, or T register (except KQ, 
SO, S3, or S4) . 

msgetass Class where the message is to be assigned. Only current 
class is JCLMSG. msgetass can be a symbol or an A, S, or 
T register (except AO, SO, S2, S3, or S4) containing the 
message class. 

ovevvtde Message suppression override flag; if present message is 
to go to $LOG regardless of ECHO status. 



CSECHO - ECHO A CONTROL STATEMENT TO THE LOGFILE 

The control statement at the specified location is entered into the 
system log and user logfile. This macro will not echo the control 
statement to the user logfile if the statement originated as terminal 
input from an interactive job. Echoing is also governed by the current 
ECHO state for JCL statements. (See part 2, section 2, ECHO control 
statement.) 



Format: 



Location 


Result 


Operand 




CSECHO 


address 



address A symbol or an A, s, or T register (except SO, SI, S2) that 
contains the base address of the control statement image. 
This is a required parameter. 
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MODE - SET OPERATING MODE 

The MODE macro sets the floating-point error flag in the M register of 
the job's exchange package. This flag controls whether or not a 
floating-point error will cause an interrupt flag to be set in the 
Flags (F) register. An exit from the program occurs on a 
floating-point error only when the floating-point error flag has been 
set. 



Format: 



Location 


Result 


Operand 




MODE 


M=mode 



M=mode 



Operating mode. May be any of the following: 



DFI, 1, or 2 
EFI, 3, or 4 



Disable floating-point interrupt 
Enable floating-point interrupt 



SWITCH - SET OR CLEAR SENSE SWITCH 

The SWITCH macro allows a user to turn on (set) or turn off (clear) pseudo 
sense switches. 



Format: 



Location 


Result 


Operand 




SWITCH 


n,x 
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n 



X 



Number of switch (1-6) to be set or cleared 

Switch position 

ON Switch n is turned on; set to 1 
OFF Switch n is turned off; set to 



JTIME - REQUEST ACCUMULATED CPU TIME FOR JOB 

The accumulated CPU time for the job is returned at the location 
specified in the macro call. The time in seconds is expressed in 
floating-point form. 



Format: 



Locat ion 


Result 


Operand 




JTIME 


address 



address A symbol or an A, S, or T register that contains the 
address at which to return the accumulated CPU time 



RECALL - RECALL JOB UPON I/O REQUEST COMPLETION 

This function removes a job from processing. The job does not become 
a candidate for processing until the previously issued I/O request for 
the specified dataset is completed or partially completed, that is, 
the job is resumed when another block of data is transferred to or 
from the user's buffer or when the I/O request is completed. 



Format: 



Location 


Result 


Operand 




RECALL 


address 
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address Symbolic address of the Open Dataset Name Table (ODN) or 
Dataset Parameter Area (DSP) for this dataset or an A, 
S, or T register containing the ODN or DSP address. See 
description of OPEN macro (this section) and DSP table 
(Appendix A) . 



DELAY - DELAY JOB PROCESSING 

This function removes a job from execution and delays the job from 
becoming a candidate for processing until the number of milliseconds 
(specified in the word at the given address) has elapsed. 



Format: 



Locat i on 


Result 


Operand 




DELAY 


address 



address A symbol or an A, S, or T register containing the 
address of the word that contains the number of 
milliseconds to delay 



ABORT - ABORT PROGRAM 

The ABORT request provides for abnormal termination of the current 
program. Processing resumes with the first job control statement 
following the next EXIT statement unless reprieve processing is 
enabled. If no such statement exists, the job is terminated. 



Format: 



Locat i on 



Resu 1 t 



Operand 



ABORT 
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SETRPV - SET JOB STEP REPRIEVE 

The SETRPV request enables the user's current job step to maintain 
control when a job step abort error condition occurs or upon normal 
termination of the job step. Once enabled by the user, reprieve 
processing remains in effect until the job step terminates, a selected 
error condition occurs, or the user clears the reprieve processing 
capability. 

If a selected error condition occurs, the user is reprieved from the 
normal or abnormal job step termination. The reprieve processing code 
that is given control may attempt a recovery or continue with the 
normal or abort termination. 

I/O errors from $SYSLIB or $FTLIB are not readily recognizable or 
correctable. At the $FTLIB level, FORTRAN I/O usually involves three 
steps: initialization, transfer, and termination. I/O errors almost 
always occur at the transfer stage; because termination does not occur 
in this case, any further attempts at initialization fail, thus 
hampering correction. Any errors reported by the logical I/O routines 
look like user-requested aborts. 

Two types of error conditions are related to a job step: nonfatal and 
fatal. Nonfatal error conditions may be reprieved any number of times 
per job step by the user. Each fatal error condition may be reprieved 
only once per job step. The second occurrence of the same fatal error 
condition results in an immediate termination of the job step. 

Refer to Appendix F for system error codes and the mask value for each 
code. 



Format: 



Location 


Result 


Operand 




SETRPV 


entry ^ xpsave^ mask 
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entvy Address to which control is passed if reprieve 

processing is selected for the respective error 
conditions. 

arpsave First word address (FWA) of the area into which the 

system copies the user's exchange package when control 
is passed to the user's reprieve processing code. This 
area is formatted as follows, and the contents are those 
at the time of the error. 



16 
17 

18 

19 

20 



40 



XP 



VMR 



ESW 



SEC 



Reserved for system use 



XP User exchange package (refer to Appendix E) 

VMR User vector mask register 

ESW Error status word. Contains the octal value 
of the error category reprieved (refer to 
description of mask) . 

SEC Actual system error code (refer to Appendix P) 

mas'k Address of a user specified octal value indicating the 

class (es) of error condition (s) for which to enable 
reprieve processing. Any number of classes may be 
specified by combining the appropriate octal mask values 
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Class 
(Octal mask value) 



1 

2 

4 

10 

20 

40 

100 

200 

400 

1000 

2000 

4000 

10000 



Reprievable Error Condition 

Disable user reprieve processing 

Normal job step termination 

User requested abort 

System abort 

Operator DROP 

Operator RERUN 

Memory error 

Floating point error 

Time limit 

Mass storage limit exceeded 

Memory limit exceeded 

Link transfer error 

Security violation 

Interactive console 'attention' 

interrupt 



NOTE 

The system disables reprieve processing once 
the user's reprieve processing code gains 
control. To be reprieved from future error 
conditions the user must issue another 
SETRPV request. 



CONTRPV - CONTINUE FROM REPRIEVE CONDITION 

The CONTRPV macro continues normal job processing from within a 
reprieve subroutine. The program address to continue processing and 
all A, S, and VL register values are taken from the user-supplied 
exchange package. 



Format : 



Location 



Result 



CONTRPV 



Operand 



XP 
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ENDRPV - END REPRIEVE PROCESSING 

The ENDRPV request is used to return to job step termination processing. If 
the step completed normally, normal termination is completed. If the step 
aborted, abort processing is resumed. 



Format 



Location 



Result 



Operand 



ENDRPV 



ROLL - ROLL A JOB 

A user can protect a job against system interruption via the ROLL 
request. Rolling a job causes it to be written to disk so that the job at 
that point in time can be recovered in the event of a system 
interruption. Once a job has been rolled, it remains recoverable unless 
it loses the recoverable status (by altering a permanent dataset, for 
example) . Once a job loses its recoverable status, the user may request 
another ROLL to continue to protect the job against system interruption. 



Format : 



Location 



Result 



ROLL 



Operand 



ENDP - END PROGRAM 

The ENDP request is used for normal termination of the current program. 
Processing resumes with the next job control statement if reprieve 
processing is not enabled for normal job step termination. If no such 
statement exists, the job is terminated. 



Format: 



Location 


Result 


Operand 




ENDP 
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NORERUN - CONTROL DETECTION OF NONRERUNNABLE FUNCTIONS 

The NORERUN request instructs the system to begin or cease monitoring of 
user operations for nonrerunnable functions. This request determines 
whether execution of such functions will make the job become nonrerunnable 
but does not affect the current rerunnability of the job. 



Format: 



Location 


Result 


Operand 




NORERUN 


pavameter 



parcmeter 



ENABLE causes the system to begin (or continue) monitoring 
user functions for nonrerunnable operations 

DISABLE causes the system to stop monitoring user operations 
for nonrerunnable functions 

A symbol identifying a location or an A, S, or T register 
containing the address of a location which contains either a 
for ENABLE or a 1 for DISABLE. 



RERUN - UNCONDITIONALLY SET JOB RERUNNABILITY 

The RERUN request instructs the system to mark the job as either 
rerunnable or nonrerunnable regardless of functions previously performed, 
The future declaration of nonrerunnability is not affected. 



Format: 



Location 


Result 


Operand 




RERUN 


parcmeter 



parameter 



ENABLE causes the system to mark the job rerunnable 
DISABLE causes the system to mark the job not rerunnable 
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A symbol identifying a location or an A, S, or T register 
containing the address of a location which contains either a 
for ENABLE or a 1 for DISABLE. 



lOAREA - CONTROL USER ACCESS TO I/O AREA 

The lOAREA request instructs the system to either allow or deny access to 
the user's I/O and Dataset Parameter Area (DSP) areas. This request can 
also be used to restore the status of these areas to their initial 
status. Initially, the user I/O area is assumed to be unlocked. 



Format: 



Location 


Result 


Operand 




lOAREA 


key J, save 



key May equal any of the following: 

LOCK Denies access to the user's I/O buffers and DSP 
area. The Limit Address is set to the address 
specified in JCDSP. (All user logical I/O calls 
which require access to the DSP area or I/O buffers 
involve an exchange to the operating system before 
and after I/O processing.) 

UNLOCK Gives full access to the user's I/O buffers and DSP 
area. The Limit Address is set to the value 
specified in JCFL, 

RESTORE Reserved for use by the FORTRAN library. If UNLOCK 
was used previously to unlock the I/O area, then 
RESTORE locks the area. 

save Symbolic address where lock status is to be stored; required 

only if RESTORE is to be used. The current status of key 
is stored in one word. 
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DUMPJOB - DUMP JOB IMAGE 

The DUMPJOB request causes the current job image (including the Job 
Table Area) to be written to a specified local dataset. If the 
dataset already exists, it is rewound; otherwise, a new dataset is 
created for the dump. The dump is formatted as suitable for the dump 
utility. 



Format : 



Location 


Result 


Operand 




DUMPJOB 


DN=dn 



DN=dIn A symbol or an A, S, or T register (not AO or SO) containing 
the address of a dataset name. If dn is not specified, 
$DUMP is assumed. If location dn is not defined, the 
DUMPJOB macro generates the symbolic location. 



DATASET MANAGEMENT 

The system action request macros involved with dataset management allow 
the user to open datasets; set up tables; and close, release, or dispose 
datasets. System action request macros available include DSP, OPEN, 
CLOSE, RELEASE, DISPOSE, and SUBMIT. 



DSP - CREATE DATASET PARAMETER AREA 

The DSP macro creates a table in the user field called the Dataset 
Parameter Area (DSP) • This table holds information concerning the status 
of the named dataset and the location of the I/O buffer for the dataset. 
The DSP is illustrated in Appendix A of this manual. 

The DSP macro should be used only when the user needs the DSP and I/O 
buffer in the user-managed memory portion of the job. Normally a DSP and 
buffer for a dataset are created in the high end of the job's memory 
(above JCHLM) by execution of an OPEN macro. 
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when using the DSP macro, the user must also set up a two-word Open 
Dataset Name Table (ODN) . This ODN must be defined before using an OPEN 
macro specifying this dataset. 

The DSP macro is not executable; it merely sets up a DSP table with the 
dataset name, first, in, out, and limit fields initialized. An OPEN macro 
must be executed to make the DSP known to the system. 



Format : 



Location 


Result 


Operand 


loe 


DSP 


dn,first,nb 



loo Symbolic address of DSP. If toe is not specified, the 

address of the dataset name is generated. 

dn Dataset name 

first Address of the first word of the user-allocated buffer for 

this dataset 



nh 



Number of 512-word blocks in the dataset buffer 



Example : 



Location 



Result 



Operand 



Comment 



Bna 



X 

ODN 



DSP 
CON 
CON 



OPEN 



2SL 



XFIL,BUF,1 

•XFIL'L 

XFIL@ 



ODN, I 



IL 



ASCII name 
Address of DSP 
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OPEN - OPEN DATASET 

The OPEN macro prepares a dataset for processing. When an OPEN macro is 
executed, the dataset is made known to the system if it is not an existing 
dataset. I/O tables are created in the high end of the job's memory; 
included are the Dataset Parameter Area (DSP) and the Logical File Table 
(LFT) . An I/O buffer is created if the dataset is COS blocked format, but 
not for an unblocked dataset. The address or offset of the DSP table is 
returned to the user. 

An OPEN macro may be executed on a dataset that is already open. 



Format : 



Location 


Result 


Operand 




OPEN 


dn,pd,ldt 



dn 



pd 



Idt 



Dataset name. The OPEN macro generates a 2-word Open 
Dataset Name Table (ODN) the first time an OPEN of the 
dataset is encountered, unless the user has previously 
generated an ODN for the dataset. (The ODN is illustrated 
in Appendix A.) The dn becomes the symbolic address of 
the ODN. It is used in all references to the dataset in 
other I/O requests. 

As an alternative, dn may be an A, S, or T register (not 
AO, SO, or S2) containing the ODN address. 

Processing direction. May be any of the following: 

I Dataset opened for input 

Dataset opened for output 

10 Dataset opened for input/output (default) 

pd may alternatively be an S or T register (but not an A 
register) with bit set for input and/or bit 1 set for 
output. 

Label Definition Table (LDT) ; an optional parameter that is 
the name of a previously defined LDT for tape processing. 
The pointer to this field will be placed in the ODN built by 
the macro. The parameter applies to tape datasets only. 
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If the DSP pointer in the ODN is negative or zero, the OPEN call returns 
the negative DSP offset in the DSP field of the ODN. The actual DSP 
address is equal to (JCDSP) - negative DSP offset, where (JCDSP) is the 
value of the JCDSP field of the Job Coiranunication Block, The negative DSP 
offset of a dataset does not change when a job's field length changes or 
as additional datasets are opened or closed. 

If the DSP pointer in the ODN is positive and greater than zero, OPEN 
assumes the DSP field contains the address of the user's own DSP in the 
user field between the Job Communication Block and (JCHLM) (the value in 
the JCHLM field of the JCB) . The system uses the DSP indicated and does 
not allocate an additional DSP or buffer in the job's I/O table area. The 
DSP indicated must already contain the buffer pointers and must indicate a 
buffer also within the user field. If the dataset is memory resident, 
this buffer should be large enough to contain the entire dataset plus one 
block. 



Examples : 

1. In the following example, the OPEN generates an ODN for dataset 
DSETONE unless one has been previously generated for that dataset . 
The dataset is opened for input/output processing. 



Location 


Result 


Operand 


Comment 


1 


LO 


20 


35 


L 


OPEN 


DSETONE, 10 





2. In this example, the address of the ODN generated by this OPEN call is 
passed via register SI; S2 contains processing direction information. 



Location 



Result 



Operand 



Comment 



OPEN 



20 



35 



S1,S2 



3. In this example, the dataset ATAPE is opened for output with LABELX as 
the Label Definition Table. An ODN for ATAPE has not yet been defined. 



Location 


Result 


Operand 


Comment 


1 


10 


20 


35 




OPEN 


ATAPE, 0, LABELX 
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CLOSE - CLOSE DATASET 

CLOSE releases the buffer and the Dataset Parameter Area (DSP) for a 
cos-managed dataset. Disk space is not released and the dataset remains 
attached to the job. 

The buffers are flushed if all of the following conditions are true for 
the dataset: 

1. The dataset is currently opened for output. 

2. No end-of-data is written. 

3. The dataset is being written sequentially. 

4. The dataset' s DSP is managed by COS. 

5. It has COS blocked dataset structure. 

6. It is not memory resident. 



Format : 



Location 


Result 


Operand 




CLOSE 


dn 



dn 



Dataset name. Symbolic address of the Open Dataset Name 
Table (ODN) for this dataset or an A, S, or T (not AO or SO) 
register containing the address of the ODN. See description 
of OPEN macro. 



RELEASE - RELEASE DATASET TO SYSTEM 

The dataset whose Dataset Parameter Area (DSP) address is at the location 
specified in the macro call is returned to the system. The dataset is 
closed and the Dataset Name Table (DNT) entry is released. Additional 
system action depends on the type of dataset. Output dataset s are routed 
to a front end. If a dataset is not a permanent dataset, the disk space 
associated with that dataset is returned to the system. The dataset is no 
longer attached to the job. 



Format : 



Location 


Result 


Operand 




RELEASE 


addres 8, EOLD 
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address Symbolic address of the Open Dataset Name Table (ODN) or 

Dataset Parameter Area (DSP) for this dataset or an A, S, or 
T register containing the ODN or DSP address. See 
description of OPEN and DSP macros (this section) and of DSP 
format (Appendix A) . 

HOLD Hold generic device; optional parameter. If specified, the 
generic system resource associated with this dataset will 
not be made available to another job when the dataset is 
released. This parameter is for tape dataset s only and is 
ignored for mass storage datasets. 



DISPOSE - DISPOSE DATASET 

The DISPOSE macro places a dataset in the appropriate queue as defined by 
the PDD macro. 



Format: 



Location 


Result 


Operand 




DISPOSE 


pddtag 



pddtag Address of PDD macro call 

SUBMIT - SUBMIT JOB DATASET 

The SUBMIT macro places a job dataset into the CRAY-1 job input queue. 

Format : 



Location 


Result 


Operand 




SUBMIT 


pddtag 



pddtag Address of PDD macro call 
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TIME AND DATE REQUESTS 

Several system action request macros inform the user of the current time 
or date and the Julian date. These include TIME, DATE, and JDATE. 



TIME - GET CURRENT TIME 

The current time in ASCII is returned at the location specified in the 
macro call. The format of the time is as follows: 







15 



23 



39 



hi 



63 



h h 


; 


m m 


: 


s s 



Format: 



Location 


Result 


Operand 




TIME 


addvess 



address a symbol or an A, S, or T register that contains the 
destination address of the current time 



DATE - GET CURRENT DATE 

The current date in ASCII is returned at the location specified in the 
macro call. The format of the date is as follows: 



Q 




15 




2? 






39 




i+7 




6 


m 


m 




/ 


d 


d 




/ 




y 


y 



The order can be changed to day, month, and year (the European format) 
through an installation parameter. 
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Format: 



Location 


Result 


Operand 




DATE 


address 



address A symbol or an A, S, or T register that contains the 
destination address of the current date 



JDATE - RETURN JULIAN DATE 

The current Julian date in ASCII is returned at the location specified in 
the macro call. The format of the date is as follows: 



i+O 



63 



y y 


d d d 


AAA 



Five ASCII characters are left-adjusted with blank fill in the reply 
word. The first two characters are the year; the next three are the 
number of the day in the year. 



Format: 



Location 


Result 


Operand 




JDATE 


address 



address a symbol or an A, S, or T register that contains the 
destination address of the current Julian date 
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DEBUGGING AIDS 

The system action request macros in this category permit the user to 
selectively read or write information during a program run to aid in the 
debugging process. Included are the SNAP, DUMP, INPUT, OUTPUT, FREAD, 
FWRITE, UFREAD, UFWRITE, SAVEREGS , and LOADREGS macros. The first four of 
these macros can be made conditional using the label DEBUG. 



SNAP - TAKE SNAPSHOT OF SELECTED REGISTERS 

The SNAP macro writes the contents of selected registers under the control 
of FORTRAN-style formats selected by the user. 

The macro generates exactly three words of inline code; the rest of the 
logic is in a unique subroutine created by the macro. 

The DEBUG' option allows conditional execution of the SNAP macro. If the 
label on the SNAP statement is DEBUG, no label is defined for the 
generated code. Instead, unless the symbol DEBUG has been set to 1 by a 
previously assembled SET or equate statement, code generation within the 
macro is suppressed entirely. 



Format : 



Location 


Result 


Operand 




SNAP 


{list) ,Ulill=unit ,AF=fmt ,BF=fmt , 
SF=fmt ,TF=fmt ,VF=fmt ,ML=n 



list A list of registers and register groups separated by 

commas. The list need not be enclosed in parentheses if 
it contains only one element. Within the list, null 
elements are ignored so that each element can be 
preceded and followed by blanks. However, an element 
cannot contain embedded blanks. Each element of the 
list that is not null must have one of the following 
forms : 



R 



Writes the contents 6f all R registers 
(where R is A, B, S, T, or V) 



R, 



Writes the contents of register R^ (for 
example, A7) 
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Writes the contents of registers R^ 
through Rj (for example, A1-A4 or Al-4) 

Each "t or 3 must be either an octal number or 
a previously defined register designator (for 
example, B.SEP). 

There is no limit to the number of elements in the list 
or to the number of occurrences of a particular 
register. If the list is empty, no output is produced 
except for the usual header. The header, which is 
always produced, shows the contents of P and BO as 
parcel addresses. 

UNlT=wnit A local dataset name, an expression containing only 

previously defined terms that resolves into a FORTRAN unit 
number, or the previously defined label of a word 
containing either a local dataset name or a FORTRAN unit 
number. The default is $OUT. 

hF=fmt A register format in decimal; the default is (8(3X08)) 

BF=fmt B register format in decimal; the default is (8(3X08)) 

SF=fmt S register format in decimal; the default is (4025) 

TF=fmt T register format in decimal; the default is (4025) 

VF=fmt V register format in decimal; the default is (4025) 

VL=n Number of V register elements to be snapped. The default 
is VL=VL. The caller can also specify VL=VL+1 or an 
absolute expression. If VL is or 64, then VL=VL+1 means 
64 rather than 65. The default radix of n is decimal 
unless a BASE or BASE M is in effect. 

RETURN CONDITIONS: 

All registers are saved, including the vector registers and VL. 



DUMP - DUMP SELECTED AREAS OF MEMORY 

The DUMP macro performs a formatted dump of selected memory areas. 

The macro generates exactly three words of inline code; the rest of the 
logic is in a unique subroutine created by the macro. 
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The DEBUG option allows conditional execution of the DUMP macro. If 
the label on the DUMP statement is DEBUG, no label is defined for the 
generated code. Instead, unless the symbol DEBUG has been set to 1 by 
a previously assembled SET or equate statement, code generation within 
the macro is suppressed entirely. 

Format : 



Location 


Result 


Operand 




DUMP 


(list) ,UNIT=wntt 



list A list of memory ranges separated by commas. The list 

need not be enclosed in parentheses if it contains only 
one range. There is no limit to the number of ranges in 
the list. Within the list, null elements are ignored, 
so that each memory range can be preceded and followed 
by blanks. However, a memory range cannot contain 
embedded blanks. Each non-null range must have one of 
the following forms: 

f,.l Dump memory from address / to address l-l 

f Dump memory word / 

f(n) Dump n words starting at memory address / 

/, I, or n can be numbers, labels, register names, or a 
combination of labels and numbers. Indirect addressing, 
using the at sign (@) as a prefix, is allowed. For 
numbers, the default radix is decimal unless a BASE or 
BASE M is in effect. 



Examples : 
(O'200. .O'400) 
(0(D'128)) 



Words 200q through 377q 

Words through 177g (the Job 
Communication Block) 



(R.A1(R.A2)) 
(@R.A1(@R.A2)) 



The starting address is given in Al and 
the word count is given in A2 

The starting address is given in the 
memory word addressed by Al and the 
word count is in the memory word 
addressed by A2 
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(R.A1..R.A2) The address given in Al through the 

address immediately before the address 
given in A2 

(@R.A1. .@R.A2) The address given in the memory word 
addressed by Al through the address 
immediately before the address given in 
the memory word addressed by A2 

(TABLE(R.A.BU) ) The first n words of TABLE, where n is 
held in register A.BU 

(TTT-1(@R.B77) ) The first n words following and 

including TTT-1, where n is held in the 
memory addressed by register B77 

(@PTR(@LTH)) The word addressed by PTR is the start, 
and the word count is in the word 
addressed by LTH 

(@P. .@Q,@A(@L) ) Two ranges are dumped. The first range 
is from the word addressed by P through 
the word immediately before the word 
addressed by Q; the second begins at 
the word addressed by A and includes 
the number of words given by the value 
contained in the memory cell addressed 
by L. Only the low-order 24 bits in P, 
Q, A, and L are considered in 
determining the addresses. 

lJlilT=unit A local dataset name, an expression containing only 

previously defined terms that resolves into a FORTRAN unit 
number, or the previously defined label of a word 
containing either a local dataset name or a FORTRAN unit 
number. The default is $OUT. 

RETURN CONDITIONS: All registers are saved and restored, 

including the vector registers and VL. 



INPUT - READ DATA 

The INPUT macro reads data resident on a dataset or characters already 
located in memory and assigns values to variables, words of an array, 
or registers. Its syntax is as close as possible to the syntax of the 
INPUT statement in SKOL. 
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The macro generates its code either inline or in a unique subroutine 
created by the macro. In the latter case, exactly three words of code 

are generated inline. 

The DEBUG option allows conditional execution of the INPUT macro. If 
the label on the INPUT statement is DEBUG, no label is defined for the 
generated code. Instead, unless the symbol DEBUG has been set to 1 by 
a previously assembled SET or equate statement, code generation within 
the macro is suppressed entirely. 

Format : 



Location 


Result 


Operand 




INPUT 


{list) ,SV=l^^^ ,IN=("^^^ ,UNIT=wn-z:t, 
(NO NO 1 

STRlNG=addr' , hlE=length , Emi=addv , 

ERR=ad(ir' 



list A list of input elements, each of which may include a 

variable name, an array specifier, and a format item. The 
list need not be enclosed in parentheses if it contains only 
one element. If it consists of more than one element, the 
elements are separated by commas. Null elements are 
ignored, so that each list element may be preceded and 
followed by blanks. However, an element cannot contain 
embedded blanks. Each element non-null must have one of the 
following forms: 

'.fmt A format item not associated with a variable, 

such as : 2x or :/ 

Vav'.fmt A variable name and the format used to read a 
value into it 

The format can contain any of the edit descriptors 
available to the CRAY-1 FORTRAN (CFT) user. The format 
cannot contain commas unless the entire list item is 
enclosed in parentheses. 

The variable can refer to a single word, to an array, to a 
single register, or to an array of registers, and can take 
any of the following forms: 

addv Change the contents of a single word (for 

example, LABEL-2 or W.177 



addv (oount) 



Read values for count words beginning at addv 
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addr {count liner ) 

Read values for count words beginning at addr and 
applying an increment of -incr after each word. 
The default value for incr is 1. 

R.m Change the contents of register m (where r is A, 

B, S, or T and n is an octal register number or a 
register designator of the form ,name.) 

R.VL or R.VM 

Change the current vector length or vector mask 

R.m (count) 

Change count registers starting with rn, as in 
R.A1(5) 

R.Vn {count) 

Change the first count elements of Vn 

R.vn+e Change the eth element in Vn 

R,vn+e {count) 

Change count elements, beginning at the eth 

element in Vn 

In all of the above, n must be either an octal number or a 
previously defined register designator, count and e may be 
represented by any absolute expression, in which the 
default radix is determined by the calling program. 

The variable can also refer indirectly to a word or to an 
array, using a saved register or a word in memory as a 
pointer. The forms begin with the at sign (@) and include: 

^ddr Modify the word addressed by addr 

%iddr {count) 

Modify count words beginning with the word 
addressed by addr 

Qaddr {count liner ) 

Modify count words beginning with the word 
addressed by addr, applying an increment of incr 
after each word 

@R.r»n Modify the word addressed by register m 

&R.m {count) 

Modify count words beginning with the word 
addressed by register m 
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SV=j^^S| Save flag. If SV=NO, the SAVEREGS and LOADREGS macros 
(NO ; 3j,Q j^Q^ invoked, and registers cannot be used for input 
values; IN=YES must also be specified when SV=NO. The 
default is SV=YES, which saves and restores all registers. 

IN=(YES 1 Inline code flag. If IN=YES, all the code necessary to 
^ ' perform the INPUT (except the standard subroutines called 
by the SAVEREGS and LOADREGS macros) is generated inline. 
The default is IN=NO, which causes 3 words of code to be 
generated inline; the rest is contained in a subroutine 
created by the macro. 

UNIT=wnit A local dataset name, an expression containing only 

previously defined terms that resolves into a FORTRAN unit 
number, or the previously defined label of a word 
containing either a local dataset name or a FORTRAN unit 
number. The default is $IN. 

STRI NG=e tr'in^ 

Address of a packed character string that resides in 
memory. When used in conjunction with the LTH parameter, 
the STRING parameter allows input (decoding) from the 
string. The END and ERR parameters cannot be used with 
STRING and LTH. 

LTE=length 

Number of characters to be decoded from string 

EliD=addr Optional address to which a branch occurs if an end-of-file 
is encountered 

ERR=iaddr Optional address to which a branch occurs if an error is 
encountered during the read 



RETURN CONDITIONS: All registers, including the vector registers and 

the vector length register, are saved and 
restored when SV=YES (the default) . 



OUTPUT - WRITE DATA 

The OUTPUT macro transfers variable values and character strings from a 
user's data area to a dataset or to an area in memory. Its syntax is as 
close as possible to the syntax of the OUTPUT statement in SKOL. 

The macro generates its code either inline or in a unique subroutine 
created by the macro. In the latter case, exactly three words of code 
are generated inline. 
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The DEBUG option allows conditional execution of the OUTPUT macro. If 
the label on the OUTPUT statement is DEBUG, no label is defined for the 
generated code. Instead, unless the symbol DEBUG has been set to 1 by a 
previously assembled SET or equate statement, code generation within the 
macro is suppressed entirely. 



Format: 



Location 



Result 



Operand 



OUTPUT 



(list) ,SV=P^SLlN=P^S|,UNIT=wnit;, 
[NO I (NO I 

BUFFER=a(idr» , i/£R=length 



list A list of variable names, array names, format items, and 

string constants separated by commas. The list need not be 

enclosed in parentheses if it contains only one element. If 
it consists of more than one element, the elements are 
separated by commas. Null elements are ignored, so that 
each element can be preceded and followed by blanks. 
However, an element cannot contain embedded blanks unless it 
is enclosed in a second level of parentheses. Each non-null 
element must have one of the following forms: 

'string* or * string* 

Represents any character string. The list item 
must be enclosed in parentheses if the string 
contains any blanks or commas. If the string 
is delimited by apostrophes, any inner 
apostrophes must be doubled. If it is 
delimited by asterisks, no inner asterisks are 
allowed. 



ifmt 



Represents a format item that is not associated 
with any variable (for example, :2X, :/, or 
::). The list item must be enclosed in 
parentheses if fmt contains any commas or 
blanks. 
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$PAGE, $SKIP, and $LINE 

These special format items do not require a 
colon prefix. They generate FORTRAN-style 
carriage control characters at the beginning 
of a line. When $SKIP or $PAGE is the first 
list element, the appropriate literal 
character (0 or 1) becomes the first element 
of the OUTPUT format. $LINE is assumed to be 
present by default unless the first list 
element is a format item {:fmt) , If $LINE, 
$SKIP, or $PAGE occurs later in the list, a 
comma and a slash are inserted before the 
carriage control literal in order to force a 
new line. 

vav:fmt Represents a variable name and the format to 
be used for its output 

vav::fmt The same as var:fmt, except that the 

variable's name and value are output together 

var The same as var::022 

var(,,,) The same as mr'( ...):: (4025) 

The variable can refer to a single word, to an array, to 
a single register, or to an array of registers and can 
take any of the following forms: 

addr Write the contents of a single word (for 

example, LABEL- 2 or W.177) 

addr {count) 

Write count words beginning at addr 

addr (count) 

Write count words beginning at addr 

addr ( count I -incr) 

Write count words beginning at addr and 
applying an increment of incr after each 
word. The default value for incr is 1. 

R.m Write the contents of register m (where r is 

A, B, S, or T and n is an octal register 
number or a register designator of the form 

.name) 

R.VL or R.VM 

Write the current vector length or vector mask 
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R,rn {count) 

Write count registers starting with rn, as in 
R.A1(5) 

R.vn (count) 

Write the first count elements of vn 

R.vn+e Write the eth element in Vn 

R,\m+e {count) 

Write count elements, beginning at the eth 
element in V^ 

In all of the above, n must be either an octal number or 
a previously defined register designator, count and & 
may be represented by any absolute expression. 

The variable can also refer indirectly to a word or to 
an array, using a saved register or a word in memory as 
a pointer. The forms begin with the at sign (@) and 
include: 

^addr Write the word addressed by addr 

Qaddr {count) 

Write count words beginning with the word 
addressed by addr 

%addr {count ! inor) 

Write count words beginning with the word 
addressed by addr, applying an increment 
of -incr after each word 

<^R,rn Write the word addressed by register ym 

%R,m {count) 

Write count words beginning with the word 
addressed by register rn 

SV=JYESI Save flag. If SV=NO, the SAVEREGS and LOADREGS macros 
(NO ) are not invoked, and registers cannot be used for 

output; IN=YES must also be specified if SV=NO. The 
default is SV=yES, which saves and restores all 
registers. 

IN=IyesI Inline code flag. If IN=YES, all the code necessary to 
(no ) perform the OUTPUT (except the standard subroutines 

called by the SAVEREGS and LOADREGS macros) is generated 
inline. The default is IN=NO, which means that exactly 
three words of code are generated inline; the rest is 
contained in a subroutine created by the macro. 
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UNlT=wwit 



A local dataset name, an expression containing only 
previously defined terms that resolves into a FORTRAN 
unit number, or the previously defined label of a word 
containing either a local dataset name or a FORTRAN unit 
number. The default is $OUT. 

UNIT=$LOG is treated as a special parameter value rather 
than as a dataset name. If UNIT=$LOG, the OUTPUT macro 
automatically encodes the data (using its own buffer) 
rather than writing it directly, and uses the MESSAGE 
macro to write it to both the user log and the system 
log. 

OUTPUT looks at the first 8 characters of the formatted 
line. The content of the first 8 characters of a 
message ID is: 





V/y 


% 


y//. 


i 


A 


- 


A 



where is a space. If the first 8 characters do not 
match the above, OUTPUT inserts the string: 



A 


A 


A 


A 


A 


A 


- 


A 



BUFFER=a(a(dr' 

Address of a packed character buffer used instead of an 
external dataset to accept the output 



LTH= length. 



Number of characters to be encoded (output) into the 
buffer 



RETURN CONDITIONS: 



All registers, including the vector registers 
and the vector length register, are saved and 
restored when SV=YES (the default) . 
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FREAD - READ DATA 

The FREAD macro permits a FORTRAN-like read statement that can make use 
of a previously defined format. 



Format: 



Location 



Result 



FREAD 



Operand 



fmtAUst) ,SV=(I^^^] Mll^unityEH^^addr. 



E.RR-'addr 



fmt Format; takes one of the following forms: 

addv Address of a format, possibly defined with the 

DATA pseudo instruction, as in: 
DATA ' (FIO.O) ' 



( {string) ) 



A character string enclosed in a double set of 
parentheses 



The default is (5025) . 

{list) List of addresses for which values are to be read. Even if 

there is only one item, the list must be enclosed in 
parentheses. Each item in the list specifies either the 
address of a single word or the address of an array. 

An array is handled by enclosing the array base address, the 
word count, and an optional increment in an additional set 
of parentheses. Examples: ((A, 10)) or ((B,LTH,3)) 

The CAL statement 

FREAD , ((A,10) , (B,LTH,3)) 
is equivalent to the FORTRAN statements 

READ 20, (A(I), 1=1,10), (B (3* (I-l) +1) , 1=1, LTH) 
20 FORMAT (5025) 
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An array or a single word described as a one-word array 
can be addressed indirectly by using the at sign (@) and 
the name of a variable containing the indirect address 
instead of an array name. For example: 

((@C,10)) Reads values for the first 10 words of 

an array beginning at an address held 
in variable C 

((@E,1)) Reads a value for the single word 

specified by the address held in 
variable E 

To pass a numeric address, use a W prefix (for example, 
W.177) . 

SV=JYESJ Save flag. If SV=NO, the SAVEREGS and LOADREGS macros 
(NO ) are not invoked. If SV=YES, all registers are saved and 
restored. The default is SV=NO. 

imiT=unit 

A local dataset name, an expression containing only 
previously defined terms that resolves into a FORTRAN 
unit number, or the previously defined label of a word 
containing either a local dataset name or a FORTRAN unit 
number. The default is $IN. 

EliD=addr Optional address to which a branch occurs if an 
end-of-file is encountered 

EKR=addr Optional address to which a branch occurs if an error is 
encountered during the read 



FWRITE - WRITE DATA 

The FWRITE macro permits a FORTRAN-like write statement that can make 
use of a previously defined format. 



Format: 



Location 


Result 


Operand 




FWRITE 


fmt,{list),Sy={'I^Q^\Mll=unit 
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fmt Format? takes one of the following forms: 

addr Address of a format, possibly defined with the 

DATA pseudo instruction, as in: 

DATA • (FIO.O, ' 'TEXT' ') ' 

( {string) ) 

A character string enclosed in a double set of 
parentheses (for example, ( (FIO.O, "TEXT" )) ) 

The default is (5025) . 

Hist) List of addresses whose contents are to be written. Even 

if there is only one item, the list must be enclosed in 
parentheses. Each item in the list specifies either the 
address of a single word or the address of an array. 

An array is handled by enclosing the array base address, 
the word count, and an optional increment in an additional 
set of parentheses. Examples: ((A,10)) or ((B,LTH,3)) 

The CAL statement 

FWRITE ,((A,10) ,(B,LTH,3) ) 
is equivalent to the FORTRAN statements 

PRINT 20, (A(I), 1=1,10), (B(3*(I-1)+1) , 1=1, LTH) 
20 FORMAT (5025) 

An array or a single word described as a one-word array can 
be addressed indirectly by using the at sign (@) and the 
name of a variable containing the indirect address instead 
of an array name. For example: 

((@C,10)) Reads values for the first 10 words of an 
array beginning at an address held in 
variable C 

((@E,1)) Reads a value for the single word 

specified by the address held in variable E 

To pass a numeric address, use a W prefix (for example, 
W.177) . 

sy=:JYESJ Save flag. If SV=NO, the SAVEREGS and LOADREGS macros 
(NO ) ^j.g j^Q^ invoked. If SV=YES, all registers are saved and 
restored. The default is SV=NO. 
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UN IT= wnit 



A local dataset name, an expression containing only 
previously defined terms that resolves into a FORTRAN 
unit number, or the previously defined label of a word 
containing either a local dataset name or a FORTRAN unit 
number. The default is $IN, 



UFREAD - UNFORMATTED READ 

The UFREAD macro performs a FORTRAN- like unformatted read, 

Format: 



Location 


Result 


Operand 




UFREAD 


(yes) 

un'it,{l'ist),Sy=w,r. },£HD=addr 
ERR=addr ^ * 



unit A local dataset name, an expression containing only 

previously defined terms that resolves into a FORTRAN unit 
number, or the previously defined label of a word containing 
either a local dataset name or a FORTRAN unit number. There 
is no default. 

{list) List of addresses for which values are read. Even if there 

is only one item, the list must be enclosed in parentheses. 
Each item in the list specifies either the address of a 
single word or the address of an array. 

An array is handled by enclosing the array base address, the 
word count, and an optional increment in an additional set 
of parentheses. Examples: ((A,10)) or ((B,LTH,3)) 

The CAL statement 

UFREAD , ((A,10) , (B,LTH,3) ) 
is equivalent to the FORTRAN statement 

READ (A(I), 1=1,10), (B(3*(I-1)+1) , 1=1, LTH) 

An array or a single word described as a one-word array can 
be addressed indirectly by using the at sign (@) and the 
name of a variable containing the indirect address instead 
of an array name. For example: 

((@C,10)) Reads values for the first 10 words of an array 
beginning at an address held in variable C 
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((@E,1)) 



Reads a value for the single word 
specified by the address held in 
variable E 



SV=(YES1 

(no I 



To pass a numeric address, use a W prefix (for example, 
W.177) . 

Save flag. If SV=NO, the SAVEREGS and LOADREGS macros 
are not invoked. If SV=YES, all registers are saved and 
restored. The default is SV=NO. 



E'i^D=addr Optional address to which a branch occurs if an error is 
encountered during the read 

ERR=ad(lr Optional address to which a branch occurs if an error is 
encountered during the read 



UFWRITE - UNFORMATTED WRITE 

The UFWRITE macro performs a FORTRAN-like unformatted write of output 
items separated by commas. 

Format: 



Locatron 


Result 


Operand 




UFWRITE 


YFS 

unit, {list) ,S]I= jJjQ 



unit A local dataset name, an expression containing only 

previously defined terms that resolves into a FORTRAN unit 
number, or the previously defined label of a word 
containing either a local dataset name or a FORTRAN unit 
number. There is no default value. 

{list) List of addresses whose contents are to be written. Even 

if there is only one item, the list must be enclosed in 
parentheses. Each item in the list specifies either the 
address of a single word or the address of an array. 
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An array is handled by enclosing the array base address, 
the word count, and an optional increment in an 
additional set of parentheses. Examples: ((A,10)) or 
((B,LTH,3)) 

The CAL statement 

UFWRITE $OUT, ((A,10) ,(B,LTH,3)) 
is equivalent to the FORTRAN statement 

PRINT (A(I), 1=1,10), (B(3*(I-1)+1) , 1=1, LTH) 

An array or a single word described as a one-word array 
can be addressed indirectly by using the at sign (@) and 
the name of a variable containing the indirect address 
instead of an array name. For example: 



((@C,10)) 



Writes the first 10 words of an array 
beginning at an address held in variable 
C 



((@E,1)) 



Writes the single word specified by the 
address held in variable E 



To pass a numeric address, use a W prefix (for example, 
W.177) . 

SV=|yesI Save flag. If SV=NO, the SAVEREGS and LOADREGS macros 
|N0 j are not invoked. If SV=YES, all registers are saved and 
restored. The default is SV=NO. 



SAVEREGS - SAVE ALL REGISTERS 

The SAVEREGS macro saves all of the A, B, S, T, V, VL, and VM 
registers. Additionally, it sets up words containing VL+1, P/4, 
parcel(P), BO/4, and parcel (BO) so that SNAP can handle the VL=VL+1 
option and so that SNAP, DUMP, and OUTPUT can output P and BO in 
parcel-address format. (Here, parcel (x) means the 2 low-order bits of 

X.) 



Format: 



Location 


Result 


Operand 




SAVEREGS 


lregion-],lHimE={lf} 
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region Label of the first word of a region where registers are 
to be saved. The default is QZH44HZQ. If the vegicn is 
defined, it must be with a BSS O'1230; if it is not 
defined, the SAVEREGS macro defines it. If SAVEREGS 
requests are nested, each request must specify a 
different region. 



INLINE=(^^^1 
(NO 



Inline code flag. If INLINE is omitted (as when SAVEREGS 
is invoked directly), AO is saved in word O'1200 and BO 
is saved in word O'lOOO of the region. If INLINE=YES, 
both AO and BO are lost. If INLINE=NO, BO is saved in 
word 0*1223 of the region and AO is lost. 



LOADREGS - RESTORE ALL REGISTERS 

The LOADREGS macro restores the A, B, S, T, V, VL, and VM registers 
that were saved by a previously-executed SAVEREGS macro. 



Format: 



Location 


Resu It 


Operand 




LOADREGS 


ivegion-\,mimi={]^^: 



region The region used previously in a corresponding SAVEREGS. 
no value is specified, the default is QZH44HZQ. If the 
region is defined, it must be with a BSS O'1230; if it is 
not defined, the LOADREGS macro defines it. If LOADREGS 
requests are nested, each request must specify a 
different region. 



If 



INLINE=(^^^l 
JNO j 



Inline code flag. If INLINE is omitted (as when LOADREGS is 
called by a user), AO and BO are restored from words O'1200 
and O'lOOO of the region. If INLINE=yES, both AO and BO are 
lost. If INLINE=NO, BO is restored from 0'1223, but AO is 
lost. 
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MISCELLANEOUS 

Macros that do not fit in the other categories are the SYSID, GETMODE, 
GETSWS, and INSFUN macros. 



SYSID - REQUEST SYSTEM IDENTIFICATION 

The identification of the current system is returned at the location 
specified in the macro call. The identification is returned as two 
words; the first contains the COS revision level in ASCII and the 
second contains the COS assembly date in ASCII. 



Format : 



Location 


Result 


Operand 




SYSID 


address 



address A symbol or an A, S, or T register (not AO or SO) containing 
the address where the system ID is returned 



GETMODE - GET MODE SETTING 

The GETMODE macro obtains the mode setting from the user's exchange 
package and returns it in the SI register. 



Format: 



Location 



Result 



GETMODE 



Operand 
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GETSWS - GET SWITCH SETTING 

The GETSWS macro allows the user to determine whether a specified sense 
switch number is set or not. GETSWS returns the setting of the switch 
number specified in the SI register. Sl=l if set; if not set. 



Format : 



Location 


Result 


Operand 




GETSWS 


n 



n 



Number of the switch (1-6) to be tested 



INSFUN - CALL INSTALLATION-DEFINED SUBFUNCTION 

The INSFUN macro allows the user to call any one of the 
installation-defined subfunctions defined in a subfunction table 
(INSTAB). Control is transferred to the indicated subfunction. 



Format : 



Location 


Result 


Operand 




INSFUN 


n,p 



n 



A symbol or an A, s, or T register (not AO or SO) containing 
the subfunction code 



An optional symbol. A, S or T register (not S2) , containing 
the address of a parameter list to be passed to the 
installat ion-dependent subf unc t ion . 
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LOGICAL I/O MACROS 



The logical I/O macros generate calls to I/O subroutines to be loaded 
from the subroutine library and executed as part of the user program. 
The logical I/O macros apply only to blocked datasets. Datasets 
referenced by these macros must have been opened previously by an OPEN 
macro. 

There are four main categories of logical I/O macros: synchronous 
read/write, asynchronous (buffered) read/write, unblocked read/write, and 
positioning. 



SYNCHRONOUS READ/WRITE 

The synchronous read/write logical I/O macros allow the user to read and 
write words or characters and to write an end-of-file or an end-of-data. 
Control does not return to the user program until all requested data 
transfers are completed. 

Upon termination of the READ/WRITE function, register contents are 
modified as detailed under the description of each macro, A or S 
registers not specifically mentioned should not be assumed to have any 
meaningful contents, and will not contain the same values as before the 
function request. Registers BO, B70-B77, and T70-T77 may be changed, as 
well as VL, VM, VO, and VI. Other B, T, and V registers will not be 
changed. 

Issuing a synchronous I/O macro for an unblocked dataset produces an 
error. 



READ/READP - READ WORDS 

The READ and READP macros transfer words of data that are resident on a 
dataset into the user's data area. Blank compression characters are not 
recognized, and the compressed blanks are not expanded (see part 1, 
section 2) , 
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The READ macro generates a return jump to the $RWDR subroutine, thus 
causing one record at a time to be processed. Each macro call causes the 
dataset to be positioned after the end-of-record that terminated the read. 

The READP macro generates a return jump to the $RWDP subroutine. Words 
are transmitted to the user's data area as requested by the user. Each 
call is terminated by reaching an end-of-record or by satisfying the word 
count, whichever comes first. 

No blank decompression is performed. 

When end-of-record is reached as a result of reading in word mode, the 
unused bit count from the end-of-record RCW is placed in the field DPBUBC 
of the Dataset Parameter Area (DSP) . Also, the unused bits are zeroed in 
the user's record area. 

Unrecovered data errors do not abort the job; instead control is returned 
to the caller. The caller can use the good data read, (A2) through 
(A4)-l, and then abort. The caller can also skip or accept the bad 
data.S If the caller does nothing, the job aborts when the next read 
request occurs. See the Library Reference Manual, CRI publication 
SR-0014, for detailed descriptions of SKIPBAD and ACPTBAD. 

When a READ or READP macro refers to a memory resident dataset, the first 
such macro causes the dataset to be loaded into the buffer from mass 
storage, if it exists there. If it does not exist on mass storage, the 
system I/O routines set the DSP so that it appears that the buffer is 
filled with data and no attempt is made to read data. Note that the I/O 
routines cannot distinguish between the cases (1) an existing dataset is 
declared memory resident, read in, modified in the buffer, rewound, and 
read again, and (2) no modification of data in the buffer occurs. In 
either case, the first read following a REWIND reads the unmodified data 
from disk. If an existing dataset is declared memory resident and is to 
be modified and reread, use backspace positioning macros rather than 
REWIND to reposition to beg inning-of -data to preserve the modifications. 
This is necessary only when a memory resident dataset already exists on 
mass storage. 

Formats : 







Ooerand 




READ 


dn,uda,et 



Location 




Result 
READP 



erand 



dn,uda,ct 



§ Deferred implementation 
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dn 



uda 



et 



Dataset name (symbolic address of the Open Dataset Name 
Table (ODN) for this dataset) or an A, B, or S register 
(not AO or SO) containing the Dataset Parameter Area (DSP) 
address or negative DSP offset relative to JCDSP 

User data area first word address (FWA) or an A, B, or S 
register (not Al) containing the uda address 

Word count or an A, B, or S register (not Al or A2) 
containing the number of words to be read 



RETURN CONDITIONS: 



(Al) DSP address 

(A2) FWA of user data area {uda) 

(A3) Requested word count {et) 

(A4) Actual LWA+1 of data transferred to uda, 
A4=A2 if a null record was read. 

(SO) Condition of termination 



I § Deferred implementation 



> 



End of record encountered 

Null record, end of file, end of data, 

or unrecovered data error 

encountered § 

User-specified count (A3) exhausted 

before end-of-record RCW is encountered 



(SI) Error status^ 

= No errors encountered 

= 1 Unrecovered data error encountered 

(S6) Contents of the RCW if S0£0 and S1=0; 
otherwise meaningless. Note that for 
READ/READP, the unused bit count may also 
be obtained from S6 if S0<0. Unused bits 
are not meaningful for READC/READCP, since 
the unused characters will be reflected in 
the number of characters transferred 
(A4-A2) . 
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READC/READCP - READ CHARACTERS 

The READC and READCP macros transfer character data from a dataset into 
the user data area. 

The READC macro generates a return jump to the $RCHR subroutine, thus 
causing one record at a time to be processed. Each macro call causes the 
dataset to be positioned after the end-of-record that terminated the read, 

The READCP macro generates a return jump to the $RCHP subroutine. 
Characters are transferred to the user data area as requested by the 
user. Each call is terminated by reaching an end-of-record or by 
satisfying the character count, whichever occurs first. 

One character from the record is placed, right-adjusted, zero-filled, in 
each word of the data area. Blank-compressed fields are recognized and 
expanded, one blank per word. 

Unrecovered data errors do not abort the job if the dataset is tape 
resident; instead control is returned to the caller. The caller can use 
the good data read, (A2) through (A4)-l, and then abort. The user can 
also skip or accept the bad data.§ If the caller does nothing, the job 
aborts when the next read request occurs. See Library Reference Manual, 
CRI publication SR-0014, for detailed descriptions of SKIPBAD and ACPTBAD, 

Memory resident datasets are treated as described for READ/READP macro. 



Formats: 



Location 



Result 



READC 



Operand 



dn,uda,ot 



Location Result 



READCP 



Operand 



dn,uda,et 



dn 



uda 



Dataset name (symbolic address of the Open Dataset Name 
Table (ODN) for this dataset) or an A, B, or S register 
(not AO or SO) containing the Dataset Parameter Area (DSP) 
address or negative DSP offset 

User data area first word address (FWA) or an A, B, or S 
register (not Al) containing the uda address 



§ Deferred implementation 



SR-0011 



Part 3 
3-4 



J-01 



et 



Character count or an A, B, or S register (not Al or A2) 
containing the character count 



RETURN CONDITIONS: 



Same as for READ/READP, except that the requested 
count (A3) and data-transfer length (A4-A2) is in 
characters rather than words 



WRITE/WRITEP - WRITE WORDS 

The WRITE macro generates a return jump to either the $WWDR or $WWDS 
subroutine, depending on whether an unused bit count is specified, words 
are written from the user's data area. An end-of-record RCW is written 
following each WRITE. The end-of-record RCW indicates how many bits in 
the last words are unused, if any. 

The WRITER macro generates a return jump to the $WWDP subroutine. Words 
are written from the user's data area as requested by the user. No 
end-of-record is written. 
No blank compression is performed. 

If the dataset is memory resident and the WRITE or WRITER causes the 
buffer to become full, the memory resident flags are cleared and the 
buffers are flushed to mass storage. 

To write only an end-of-record RCW, the WRITE macro with word count of 
is used. 



Formats; 



Location 


Result 


Operand 




WRITE 
WRITE 


dn,uda,et,uhe 
dn,uda,et 



Location 


Result 


Operand 




WRITER 


dn,uda,ot 
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dn Dataset name (symbolic address of the Open Dataset Name 

Table for this dataset) or an A, B, or S register (not AO 
or SO) containing the Dataset Parameter Area (DSP) address 
or negative DSP offset 

uda User data area first word address (FWA) or an A, B, or S 

register (not Al) containing the uda address 

at Word count or an A, B, or S register (not Al or A2) 

containing the word count 

ube Unused bit count or an A, B, or S register (not Al, A2, or 

A3) containing the unused bit count or null. If null, 
record contains no unused bits. 



RETURN CONDITIONS: (Al) DSP address 

(A2) FWA Of user data area (uda) 
(A3) Requested word count (et) 

WRITEC/WRITECP - WRITE CHARACTERS 

The WRITEC and WRITECP macros transfer characters from the user's data 
area to the dataset. 

The WRITEC macro generates a return jump to the $WCHR subroutine, thus 
causing one record at a time to be processed. An end-of-record RCW is 
written following each WRITEC. 

The WRITECP macro generates a return jump to the $WCHP subroutine. 
Characters are written from the user's data area as requested by the 
user. No end~of -record is written. 

One character is taken from bits 56-63 of each word of the data area 
and packed into the record, eight characters per word. Blank 
compression (see part 1, section 2) occurs. 

Memory resident datasets are handled as described for WRITE/WRITEP. 

To write only an end-of-record RCW, the WRITEC macro with character 
count of is used. 
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Formats: 



Location 


Result 


Operand 




WRITEC 


dn,uda,ot 



Location 


Result 


Operand 




WRITECP 


dn,uda,at 



dn Dataset name (symbolic address of the Open Dataset Name 

Table for this dataset) or an A, B, or S register (not AO 
or SO) containing the Dataset Parameter Area (DSP) address 
or negative DSP offset 

uda User data area first word address (FWA) or an A, B, or S 

register (not Al) containing the uda addresss 

ot Character count or an A, B, or S register (not Al or A2) 

containing the character count 



RETURN CONDITIONS 



Same as for WRITE/WRITEP except that the 
requested count (A3) is in characters rather 
than words 



WRITEF - WRITE END OF FILE 

The WRITEF macro generates a return jump to the $WEOF subroutine, 
causing an end-of-record RCW (if not previously written) and an 
end-of-file RCW to be written. 

If the WRITEF macro causes the buffer for a memory resident dataset to 
be full, the memory resident flags are cleared and the buffers are 
flushed to mass storage. 



Format : 



Location 


Result 


Operand 




WRITEF 


dn 
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dn 



Dataset name (symbolic address of the Open Dataset Name 
Table (ODN) for this dataset) or an A, B, or S register 
(not AO or SO) containing the Dataset Parameter Area (DSP) 
address or negative DSP offset 



RETURN CONDITIONS: 



(Al) DSP address 



WRITED - WRITE END OF DATA 

The WRITED macro generates a return jump to the $WEOD subroutine, causing 
an end-of-record RCW (if not previously written), an end-of-file RCW (if 
not previously written) , and an end-of-data RCW to be written. 

The WRITED macro causes buffers to be flushed. If the dataset is memory 
resident, buffers are flushed to mass storage only if the end of data 
occurs within the last block of the buffer; in this case the memory 
resident flags will also be cleared. 



Format : 



Location 


Result 


Operand 




WRITED 


dn 



dn 



Dataset name (symbolic address of the Open Dataset Name 
Table for this dataset) or an A, B, or S register (not AO 
or SO) containing the Dataset Parameter Area (DSP) address 
or negative DSP offset 



RETURN CONDITIONS: 



(Al) DSP address 



ASYNCHRONOUS READ/WRITE 

The asynchronous read/write logical I/O macros allow the user to read and 
write words and to write an end of file or an end of data. These macros 
provide the CRAY Assembly Language (CAL) programmer with the same 
capabilities as the FORTRAN BUFFER IN/BUFFER OUT statements. 

Control returns to the user immediately. It is the user's responsibility 
to ensure that requested data transfers are complete and error-free by 
examining the DSP before attempting to process input data or requesting 
additional writes. The macro BUFCHECK is provided to make the necessary 
checks. 
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All of the asynchronous blocked I/O macros use registers AO, Al, A2, SO, 
SI, and S2. Other A and S registers, and all B, T, and V registers 
remain unchanged (except BO) . Unblocked I/O processing also uses 
registers A6, S3, and S4. In all cases, after the I/O function 
completes, Al contains the DSP address. The other registers used are not 
meaningful. All status responses must be obtained from the DSP. 

Asynchronous requests for unblocked datasets require that the uda 
parameter specify the address of an area in the user's program. Also, 
the ct parameter must be a value that is a multiple of 512. 

Memory resident datasets are handled the same as for the synchronous 
read/write macros. See the description of the READ, WRITE, WRITEF, and 
WRITED macros for the handling of BUFIN(P), BUFOUT(P) , BUFEOF, and BUFEOD 
respectively. 



BUFIN/BUFINP - TRANSFER DATA FROM DATASET TO USER RECORD AREA 

The BUFIN and BUFINP macros transfer words of data from a dataset to a 
user record area. Both macros generate a system call to $CBIO. 

The BUFIN macro transfers data from the current position to end-of-record 
or until the specified word count is exhausted. The dataset is 
positioned after the end of the current record. Field DPBUBC indicates 
the count of unused bits in the last word of the record. If the word 
count is exhausted before end of record, the unused bit count is set to 
zero. 

The BUFINP macro transfers data from the current position to 
end-of-record or until the specified word count is exhausted. The 
dataset remains positioned midrecord if the word count is exhausted 
before end-of-record is reached. The unused bit count is set in the same 
way as for BUFIN. 

In both cases, control returns to the user program immediately, giving 
the user the responsibility of monitoring the proper DSP fields to 
determine when the transfer is complete and whether any errors occurred. 

If the dataset is unblocked, the specified word count is transferred. 
RCWs and BCWs are ignored. 



Formats : 



Location 


Result 


Operand 




BUFIN 


dn,uda,et,rel 
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Location 


Result 


Operand 




BUFINP 


dn,udaiet,rel 



dn Dataset name (symbolic address of the Open Dataset Name 

Table (ODN) for this dataset). It is the Dataset Parameter 
Area (DSP) address if and only if dn=kl. The ODN address 
may be given in any other A register except AO, any S 
register except SO, SI or S2, or any B register. 

uda User's record area or A, S, or T register (not AO, SO, SI, 

or S2) containing the uda address 

et Word count or A, S, or T register containing word count (not 

SI or S2) 

ret Optional recall flag. If not null, the macro expansion 

contains a RECALL loop until the I/O is completed. 

Registers SI and S2 are used to construct the parameter word (W@DPBIO) and 
may not contain parameter address or values. 

When I/O is completed, for both BUFIN and BUFINP, the actual number of 
words transferred can be obtained from the DPBWC field of the DSP. 



BUFOUT/BUFOUTP - TRANSFER DATA FROM USER RECORD AREA TO DATASET 

The BUFOUT and BUFOUTP macros transfer data from a user's record area to a 
dataset using the system F$BIO function. 

The BUFOUT macro transfers the specified number of words and writes an 
end-of-record RCW on the dataset. Optionally, an unused bit count may be 
specified, giving the number of bits in the last word of data that are not 
to be considered as part of the data. The end-of-record RCW will contain 
this unused bit count. 

The BUFOUTP macro transfers the specified number of words but does not 
write an end-of-record RCW. Subsequent BUFOUTP macro calls continue to 
construct the record. A subsequent BUFOUT macro terminates the record 
with an end-of-record. Unused bits are meaningless for BUFOUTP. 

In both cases, control returns to the user program immediately, giving the 
user the responsibility of monitoring the proper DSP fields to determine 
when the transfer is complete and whether any errors occurred. 

If the dataset is unblocked, the specified word count is transferred. 
RCWs and BCWs are ignored. 



SR-0011 



Part 3 
3-10 



J-01 



Formats : 



Location 


Result 


Operand 




BUFOUT 


dn,uda,et,ubo,rel 



Location 


Result 


Operand 




BUFOUTP 


dn,uda,et,ube,rel 



dn Dataset name (symbolic address of the Open Dataset Name 

Table (ODN) for this dataset). It is the Dataset Parameter 
Area (DSP) address if and only if dn=hl. The ODN address 
may be given in any other A register except AO, any S 
register except SO, SI, or S2, or any B register. 

uda User record area or A, S, or T register containing record 

area address (not AO, SO, SI, or S2) 

et Word count or A, S, or T register containing word count (not 

AO, SO, SI or S2) 

ube Optional unused bit count or A, S, or T register containing 

unused bit count (not AO, SO, or S2) or null. If null, 
record contains no unused bits. This field is ignored for 
BUFOUTP . 



rot Optional recall flag. If not null, the macro expansion 

contains a RECALL loop until the I/O is completed. 

Registers SI and S2 are used to construct the parameter word (WQDPBIO) and 
may not contain parameter addresses or values, except that SI may contain 
the unused bit count. 



BUFEOF - WRITE END OF FILE ON DATASET 

The BUFEOF macro is used to write an end-of-file on a dataset. Control 
returns immediately to the user program, giving the user the 
responsibility of monitoring the DPBIO field. An end-of-record is written 
if the dataset is mid-record. 

Issuing a BUFEOF macro for an unblocked dataset produces an error. 
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Format : 



Location 



Result 



BUFEOF 



Operand 

dn,vol 



dn Dataset name (symbolic address of the Open Dataset Name 

Table (ODN) for this dataset) . It is the Dataset Parameter 
Area (DSP) address if and only if dn-Al, The ODN address 
may be given in any other A register except AO, any S 
register except SO, 81, or S2, or any B register. 

rcl Optional recall flag. If not null, the macro expansion 

includes a RECALL loop until the I/O is completed. 



BUFEOD - WRITE END OF DATA ON DATASET 

The BUFEOD macro writes an end-of-data to a dataset. Control returns 
immediately to the user and it is the user's responsibility to monitor the 
DPBIO field. An end-of-record and an end-of-file will also be written, if 
necessary. 

Issuing a BUFEOD macro for an unblocked dataset produces an error. 



Format : 



Location 


Result 


Operand 




BUFEOD 


dn,vcl 



dn Dataset name (symbolic address of the Open Dataset Name 

Table (ODN) for this dataset). It is the Dataset Parameter 
Area (DSP) address if and only if dn^^hl. The ODN address 
may be given in any other A register except AO, any S 
register except SO, SI, or S2, or any B register. 

rel Optional recall flag. If not null, the macro expansion 

includes a RECALL loop until the I/O is completed. 
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BUFCHECK - CHECK BUFFERED I/O COMPLETION 

The BUFCHECK macro requests the system to wait until the buffered I/O on a 
dataset has completed and, optionally, to go to an error address if the 
DSP status contains any error flags when the I/O completes. 



Format : 



Location 



Result 



BUFCHECK 



Operand 



dn, err 



dn Dataset name (symbolic address of the Open Dataset Name 

Table (ODN) for this dataset) . It is the Dataset Parameter 
Area (DSP) address if and only if dn=Al, The ODN address 
may be given in any other A register except AO, any S 
register except SO, SI, or S2, or any B register. 

erv Optional error address, if any error bits are set in the 

DSP on completion of the I/O, control is transferred to 
err, if specified. If err is not specified, it is the 
user's responsibility to detect any errors. Note that for 
this purpose, DPEOI does not constitute an error bit. 



RETURN CONDITIONS: 



If err is specified, SI will contain the DSP 
field DPERR, right-justified. 



UNBLOCKED READ/WRITE 

The unblocked dataset read and write macros allow the user to read and 
write data directly into or from a buffer supplied by a program rather 
than by the system. The system waits for I/O to complete. 

The system does no blocking or deblocking of unblocked datasets . 

Upon termination of the READ/WRITE function, register contents are 
modified as detailed under the description of each macro. A or S 
registers not specifically mentioned should not be assumed to have any 
meaningful contents, and will not contain the same values as before the 
function request. Registers BO, B70-B77, and T70-T77 may be changed, as 
well as VL, VM, VO, and VI. Other B, T, and V registers will not be 
changed. 
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READU - TRANSFER DATA FROM DATASET TO USER'S AREA 

The READU macro transfers words of data from an unblocked dataset into an 
area specified by the caller. The READU macro generates a return jump to 
the SRLB subroutine. 



Format : 



Location 


Result 


Operand 




READU 


dn,udafOt 



dn 



uda 



et 



Dataset name (symbolic address of the Open Dataset Name 
Table for this dataset) or an A, B, or S register (except AO 
or SO) containing the Dataset Parameter Area (DSP) address 
or negative DSP offset 

User data area first word address (FWA) or an A, B, or S 
register (except AO, Al, or SO) containing the uda address 

Word count or an A, B, or S register (except AO, Al, A2, or 
SO) containing the number of words to be transferred, et 
must be a multiple of 512. 



RETURN CONDITIONS; 



(Al) DSP address 

(A2) FWA of user data area {uda) 

(A3) Requested word count (ct) 

(A4) Actual LWA+1 of data transferred 

(SO) Completion status. One of the following: 

-1.0 Operation complete, no errors 

0. Attempt to read past allocated data 

+1.0 Parity error§ 

+2.0 Unrecovered hardware error§ 



§ Deferred implementation 
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WRITEU - TRANSFER DATA FROM USER'S AREA TO DATASET 

The WRITEU macro transfers data from the user's area to an unblocked 
dataset. The WRITEU macro generates a return jump to the $WLB subroutine 



Format: 



Location 


Result 


Operand 




WRITEU 


dn,uda,ot 



dn Dataset name (symbolic address of the Open Dataset Name 

Table for this dataset) or an A, B, or S register (not AO 
or SO) containing the Dataset Parameter Area (DSP) address 
or negative DSP offset 

uda User data area first word address (FWA) or an A, B, or S 

register (not AO, Al, or SO) containing the uda address 

at Word count or an A, B, or S register (not Al or A2) 

containing the number of words to be transferred, ot must 
be a multiple of 512. 



RETURN CONDITIONS: 



(Al) DSP address 

(A2) FWA of user data area {uda) 

(A3) Requested word count (ot) 

(SO) Completion status. One of the following: 

-1.0 Operation complete, no errors 

0.0 Attempt to read past allocated data 

+1.0 Parity error§ 

+2.0 Unrecovered hardware error§ 



POSITIONING 

The user can rewind datasets, backspace records or files, get the current 
dataset position, and position datasets using the positioning logical I/O 
macros. See each macro description for register contents on return. 
Other registers mentioned as used by READ/WRITE will be meaningless on 
return. 



§ Deferred implementation 
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When a dataset is positioned backward and the last operation on the 
dataset was a write operation, an end-of-data is written (and an 
end-of-record and end-of-f ile, if necessary) . (See the WRITE, WRITEF, 
and WRITED macro descriptions for handling of memory resident datasets 
during the end-of-data processing.) If the last operation was not a 
write operation, backward positioning has no special effect on a dataset. 



REWIND - REWIND DATASET 

The REWIND macro generates a return jump to the $REWD subroutine causing 
the dataset to be positioned at beg inning-of -data. 

The REWIND macro causes all buffer pointers in the DSP to be reset to 
indicate an empty buffer. For memory resident datasets, the next read 
will cause the pointers to be reset. If the memory resident dataset 
previously existed on mass storage, any changes made to the contents of 
the buffer prior to the rewind will be lost. This is because the disk 
copy of the dataset is reread without the changes being flushed. If the 
dataset did not previously exist on disk, any changes in the buffer 
contents are preserved across the rewind and read sequence. To preserve 
changed buffer contents for a memory resident dataset that previously 
existed on disk, use BKSPF to reposition the dataset. 



Format: 



Location 


Result 


Operand 




REWIND 


dn 



dn Dataset name (symbolic address of the Open Dataset Name 

Table for this dataset) or an A, B, or S register (not AO 
or SO) containing the Dataset Parameter Area (DSP) address 
or negative DSP offset 



RETURN CONDITIONS: 



(Al) DSP address 



BKSP - BACKSPACE RECORD 



Th BKSP macro generates a return jump to the $BKSP subroutine, 
dataset is backspaced one record. If the dataset is at 
beginning-of-data, no action occurs. 



The 
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Because the backspace operation occurs within the buffer for memory 
resident datasets, such datasets receive special handling only if an 
end-of-data must be written. Changes made in the buffer contents are 
preserved. 

Issuing a BKSP macro for an unblocked dataset produces an error. 

BKSP applies to mass storage datasets only; it is illegal on tape 
datasets. 



Format : 



Location 



Result 



BKSP 



Operand 

dn 



dn Dataset name (symbolic address of the Open Dataset Name 

Table for this dataset) or an A, B, or S register 
containing the Dataset Parameter Area (DSP) address or 
negative DSP offset 



RETURN CONDITIONS: 



(Al) DSP address 



(S6) The RCW after which the dataset was 
left-positioned; equals if 
beginning-of-data is encountered. 



BKSPF - BACKSPACE FILE 

The BKSPF macro generates a return jump to the $BKSPF subroutine. The 
dataset is backspaced one file. If the dataset is at beginning-of-data, 
no action occurs. 

Because the backspace operation occurs within the buffer for memory 
resident datasets, such datasets receive special handling only if an 
end-of-data must be written. Changes made in the buffer contents are 
preserved. 

Issuing a BKSPF macro for an unblocked dataset produces an error. BKSPF 
applies to mass storage datasets only; it is illegal on tape datasets. 
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Format : 



Location 



Result 



BKSPF 



Operand 

AW iMftMm msamsmxtsam 

dn 



dn Dataset name (symbolic address of the Open Dataset Name 

Table for this dataset) or an A, B, or S register 
containing the Dataset Parameter Area (DSP) address or 
negative DSP offset 



RETURN CONDITIONS: 



Same as for BKSP 



GETPOS - GET CURRENT DATASET POSITION 

The GETPOS macro generates a return jump to the $GPOS subroutine. This 
subroutine returns the current dataset position in SI. The dataset 
position is the number of words between the beg inning-of -data and the 
present position, not counting BCWs but including RCWs. 



Format : 



Location 


Result 


Operand 




GETPOS 


dn 



dn Dataset name (symbolic address of the Open Dataset Name 

Table for this dataset) or an A, B, or S register (except 
AO or SO) containing the Dataset Parameter Area (DSP) 
address or negative DSP offset 



RETURN CONDITIONS: 



(Al) DSP address 



(SI) For a blocked dataset, SI contains dataset 
position flags. Bits 0-2 indicate position 
within records or files, bits 31-63 
indicate physical word address within the 
file, including RCWs. At 
beginning-of-data, S1=0. Bit 0=1 if 
dataset is positioned immediately following 
a RCW. Bit 2=1 if the ROW is an 
end-of-file RCW. If bit 0=0, bit 2 also 
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will equal zero, and the dataset is 
midrecord or at beg inning-of -data. Bit 1 
is unused. 

For an unblocked dataset, SI returns the 
relative position of the current block 
within the dataset. 

(S2) For an unblocked dataset, S2 contains the 
same address as is contained in bits 31-63 
of SI for blocked datasets. 

For a blocked dataset, S2 contains the 
physical word address relative to the 
beginning of the dataset, including RCWs. 



SETPOS - POSITION DATASET 

The SETPOS macro generates a return jump to the $SPOS subroutine. The 
dataset is positioned at the word indicated by the word offset specified, 
which must be at a record boundary (at beginning-of-data, or following 
end-of-record or end-of-file, or before end-of-data) . 

For an unblocked dataset, the DSP is updated to reflect the specified 
position within the dataset. No I/O request is actually issued. SETPOS 
applies to mass storage datasets only; it is illegal for tape datasets. 



Format: 



Location 


Result 


Operand 




SETPOS 


dn ,po6 



dn Dataset name (symbolic address of the Open Dataset Name 

Table (ODN) for this dataset) or an A, B, or S register 
containing the Dataset Parameter Area (DSP) address or 
negative DSP offset 

pos Dataset position. May be any of the following: 

EOD Position the dataset preceding end-of-data 

BOD Position the dataset at beginning-of-data 

^ or 1^ 

Position the dataset to the word address 
contained in the specified S or T register. If 
pos is not SI, SI is destroyed. 
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RETURN CONDITIONS: (SI) Dataset position (See GETPOS for meaning of 

flags) 

(S6) Record control word after which dataset is 
positioned, or at beg inning-of -data 



POSITION - POSITION TAPE 

The POSITION macro generates an F$POS call to position a tape dataset. 

Format : 



Location 


Result 


Operand 




POSITION 


dn, subcode 



dn Symbolic address of the ODN table for this dataset or an A, 

S, or T register containing a pointer to the ODN table 

subcode rewind is the only subcode currently supported. 



RETURN CONDITIONS: 



None 
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PERMANENT DATASET MACROS 



The permanent dataset macro instructions are a subset of the system 
function requests. Each macro generates a function code that is a call 
to COS. The function code octal value is stored in register SO; SI and 
S2 provide optional arguments. The function code is enabled when the 
program exit instruction is executed. (Note that the contents of the 
registers used are not restored after the call is completed.) See 
Appendix C for more information on system function codes. 

The permanent dataset macro instructions are divided into two 
categories: those that define and those that manage permanent datasets. 



PERMANENT DATASET DEFINITION 

The PDD macro generates a parameter table containing information about 
the dataset. The ACCESS, SAVE, DELETE, ADJUST, DISPOSE, and SUBMIT 
macros involved in permanent dataset management use the PDD table. Thus, 
the PDD macro must accompany the use of the permanent dataset management 
macros. 

The LDT macro generates a table containing information required to 
process labels for tape datasets. The LDT macro must accompany the PDD 
and ACCESS macros in a program accessing a labeled tape dataset if label 
processing is to occur. 



PDD - CREATE PERMANENT DATASET DEFINITION TABLE 

The PDD macro creates a parameter table called the Permanent Dataset 
Definition Table (PDD) . (See Appendix A for a description of the PDD 
table.) This macro is non-executable and must accompany the use of the 
ACCESS, SAVE, DELETE, ADJUST, DISPOSE, or SUBMIT macros in a program. 
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Format : 



Location 

pddtag 



Result 



PDD 



Operand 

DN=dn , PDN=pdw , SDil=sdn , iD^^id ,iiF=mf , TlD^tid, 

DF=df, DC=do,SF=sf, RT=rt,ED=ed, BD=rd,VlT=wt, 

iW=mn,DT='dt,CS=aSfLB=lb,LDT=tdt, 

(off) (off) (off) (off) 

DEFER= ON l,NRLS=|0N ,EX0=J0N LsiD=?7Zf ,DID=7Kf 

(off) (off) (off) 



pddtag Symbolic address of the PDD table 

Parameters are in keyword form; the only required parameter is DN. 

DN=(in Dataset name. DN is a required parameter. 

PDN=pdn Permanent dataset name. The default value is dn. 

SDN=e(in Staged dataset name; 1--15 alphanumeric character name by 
which the dataset will be known at the destination 
mainframe. The default is the local dataset name (DN) . 

lD=u'id User identification; 1-8 alphanumeric characters assigned 
by the dataset creator. 

MF=mf Mainframe identifier; 2 alphanumeric character 

identification. This parameter identifies the front-end 
station to which the dataset is to be staged. If omitted, 
the mainframe from which the issuing job originated is 
used. If MF is given a value of CRAY id and DC=IN, the 
dataset is disposed to the CRAY input queue, after first 
issuing a warning message. 



NOTE 



If using the DISPOSE macro, see the description of the 
DISPOSE control statement in part 2. 
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TlD=tid Terminal identifier; 1-8 alphanumeric character identifier 
for the destination terminal. The default is the terminal 
of job origin. 

DF=df Dataset format. This parameter defines whether the 

destination computer is to perform character conversion. 
The default is CB. 

df is a 2-character alpha code defined for use on the 
front-end computer system. CRI suggests support of the 
following codes: 

CD Character/deblocked, The front-end system performs 
character conversion from 8-bit ASCII, if necessary. 

CB Character/blocked. No deblocking is performed at the 
CRAY-l prior to staging. The front-end performs 
character conversion from 8-bit ASCII, if necessary. 

BD Binary/deblocked. The front-end system performs no 
character conversion. 

BB Binary/blocked. The front-end computer performs no 
character conversion. No deblocking is performed at 
the CRAY-l prior to staging. 

TR Transparent. No blocking/deblocking or character 
conversion is performed. 

IC Interchange tape datasets only. In interchange format 
each tape block of data corresponds to a single 
logical record in COS blocked format. 

Other codes may be added by the local site. Undefined 
pairs of characters may be passed but will be treated as 
transparent mode by the CRAY-l. 

DC=do Disposition code; disposition to be made of the dataset. 

The default is PR (print) . 

dc is a 2-character alpha code which describes the 
destination of the dataset as follows: 

IN Input (job) dataset. The dataset is to be queued as a 
job on the mainframe specified by the MF parameter. 

ST Stage to mainframe. Dataset is made permanent at the 
mainframe designated by the MF parameter. 

SC Scratch dataset. Dataset is deleted. 
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PR Print dataset. Dataset is printed on any printer 
available at the mainframe designated by the MP 
parameter. PR is the default value. 

PU Punch dataset. Dataset is punched on any card punch 
available at the mainframe designated by the MF 
parameter. 

PT Plot dataset. Dataset is plotted on any available 
plotter at the mainframe designated by the MF 
parameter. 

MT Write dataset on magnetic tape at the mainframe 
designated by the MF parameter. 

SF-sf Special form information to be passed to the front-end 

system; 1-8 alphanumeric characters. SF is defined by the 
needs of the front-end system. Consult on-site analyst for 
options • 

RT=rt Retention period; a value between and 4095 specifying the 

number of days a permanent dataset is to be retained by the 
system. The default is an installation-defined value. 

ED=ed Edition number; a value between 1 and 4095 assigned by the 

dataset creator. The default is the highest edition number 
known to the system. 

RD=rd Read control word; 1-8 alphanumeric characters assigned by 

the dataset creator. The default is no read control word. 

WT=wt Write control word; 1-8 alphanumeric characters assigned by 
the dataset creator. The default is no write control word. 

MN=mn Maintenance control word; 1-8 alphanumeric characters 
assigned by the dataset creator. The default is no 
maintenance control word. 

DT=dt Tape dataset generic device name or synonym. This 

parameter is required for tape datasets; it is ignored when 
used for mass storage datasets. 

Generic Name Synonym Significance 

*6250 *TAPE Device capable of 6250 bpi 
*1600 Device capable of 1600 bpi 
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CS=<3e Character set of tape dataset, for data only. This 

parameter applies only to tape datasets; it is ignored when 
used for mass storage datasets. 

AS ASCII; default. 
EB EBCDIC 

LB=ZZ? Tape dataset label processing option. This parameter 

applies only to tape datasets; it is ignored when used for 
mass storage datasets. 

BLP By-pass label processing § 

SL IBM standard-labeled tapes 

NL Unlabeled tapes; default 

AL ANSI standard-labeled tapes 

LDT=Z.d^^ Label Definition Table (LDT) . The name of the LDT for 
tape processing. This parameter applies only to tape 
datasets; it is ignored when used for mass storage 
datasets. ttd is identical to Idttag on the LDT macro. 

NEW=I I Tape dataset is to be created; the dataset must be written 

lOFP I 

I ) Starting at the beginning of information. 

ON Tape dataset to be created 

OFF Tape dataset not to be created; default. 

MSG=j^^ I Normal completion message suppression indicator. The 
(OFF] (3efauit ig OFF. 

ON Indicator is set 
OFF Indicator is cleared 

UQ=j I Unique access. If UQ is specified, write maintenance 
[OFF] and/or read permission may be granted if the appropriate 
write or maintenance control words are specified. The 
default (OFF) is multiread access if the read control word 
is specified. 



WAIT=(ON I 
(OFF) 



Job wait/nowait. If WAIT=ON is specified, the job waits 
for the dataset to be transferred to the front-end system. 
If the transfer is canceled, the job is aborted. If 
WAIT=OFF is specified, the job resumes immediately and does 
not wait for the dataset to be transferred. If the 
transfer is canceled, the job is not aborted. If the 
parameter is omitted, an installation default parameter is 
used. 



§ Deferred implementation 
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DEFER=F^ 
OFF 



Deferred disposition. When DEFER is specified, disposing 
of the dataset is delayed until the dataset is released 
either by a RELEASE request or by termination. 

The default is OFF, in which case the dataset is disposed 
immediately. 



NRLS=|ON I 
(OFF) 



No release. When NRLS=ON is specified, the dataset remains 
local to the job after a DISPOSE request has been 
processed. The default is NRLS=OFF. 



NOTE 

The dataset is available only for reading when 
NRLS=ON is specified. 



EXO=p" I Execute-only dataset. EXO=ON sets the execute-only status 
(OFF) ^^ ^ dataset. EXO=OFF clears the execute-only status. If 
omitted, the status is ignored. 

SlD=mf Default source mainframe identifier. Two alphanumeric 

characters. This parameter defines the source front-end 
station where all staging to the CRAY-l mainframe will 
default , 

DID^mf Default destination mainframe identifier. Two alphanumeric 
characters. This parameter defines the destination 
front-end station where all staging from the CRAY-l 
mainframe will default. 



NOTE 

Use of the MF parameter with either SID or DID is not 
allowed . 
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LDT - CREATE LABEL DEFINITION TABLE 

The LDT macro creates a table called the Label Definition Table (LDT) , 
(See Appendix A for a description of the LDT table) . This macro is 
non-executable and may accompany the PDD and ACCESS macros in a program 
accessing a labeled tape dataset. 



Format: 



Location 



Idttag 



Result 



LDT 



Operand 



C'r=et ,V0L= {V8ni,vsn2, » . .vsn-^) ,FSEC=fseo , 
FSEQ=fseq,GEt>i=gen, GVN= gvn, CDT=yyddd , 
XDT=yyddd , RF=rf ,MBS=mbs , RS=r6 



Idttag Symbolic address of the LDT table; identical to tdt on 
PDD macro. 

Parameters are in keyword form. 

CT=ct§ Tape dataset conversion type. Required if run-time 

record and data format conversion is to be performed. The 
default is no conversion, ot is a 3-character code 
describing the machine internal data representation. 

IBM IBM 370 and compatible 

Volume identifier list; a list of 6-character alphanumeric 
volume identifiers, separated by commas, that comprise the 
tape dataset. The maximum number of volume identifiers per 
dataset is an installation parameter. 

FSEC=^ee(3 File section number; a number from 1 through 9999 

specifying the volume in the dataset. The first section 
(or volume) of a dataset is numbered 0001. The default is 
1. 



§ Deferred implementation 
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FSEQ= fseq^ 



r 

File sequence number; a number from 1 through 9999 
identifying this file among the files of this set. 
first file is numbered 0001. The default is 1. 



The 



GEH=gen^ Generation number; a number from 1 to 9999 that 

distinguishes successive generations of the file. The 
default is 1. 

GVli=gvn^ Generation version number; a number from 1 to 9999 that 
distinguishes among successive iterations of the same 
generation. The default is 0. 

CDT=yyddd Creation date, yy specifies the year and is a number 

from 0-99. ddd specifies the day within the year and is 
a number from 001 to 366. It indicates the creation date 
for this file . 

XDT=yyddd Expiration date; same format as creation date. It 

indicates the date on which this file may be overwritten. 

RF=r»/§ Tape dataset record format, rf is a 2- to 
8-character code describing the record type. 

lU IBM U (undefined) format; default if CT=IBM. 

IF IBM F (fixed) format 

IFB IBM FB (fixed blocked) format 

IV IBM V (variable) format 

IVB IBM VB (variable blocked) format 

IVBS IBM VBS (variable blocked spanned) format 

RS=r»s Record size. If CT=IBM, expressed in units of 8-bit bytes. 

MBS=mbs Maximum tape block size; that is, the number of bytes in 

the largest tape block to be read or written. The maximum 
size allowed at the installation and the default are 
specified as installation parameters. 



§ Deferred implementation 
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PERMANENT DATASET MANAGEMENT 

The user can access, save, adjust, and delete permanent datasets by use of 
the permanent dataset management macros. All of these macros must be 
accompanied by the PDD macro in the job. 



ACCESS - ACCESS PERMANENT DATASET 

The ACCESS macro associates an existing permanent dataset with a job and 
assures that the user is authorized to use this dataset. ACCESS must 
precede any logical I/O macros for the permanent dataset. 



Format ; 



Location 


Result 


Operand 




ACCESS 


pddtag 



pddtag Address of PDD macro call 



SAVE - SAVE PERMANENT DATASET 

The SAVE macro enters a local dataset in the Dataset Catalog, making it 
permanent. A permanent dataset is uniquely identified by permanent 
dataset name, user identification, and edition number. 

SAVE has a twofold function: 

• Creation of an initial edition of a permanent dataset 

• Creation of an additional edition of a permanent dataset 

If all of the following conditions are true for the dataset, SAVE makes a 
call to close the dataset and consequently to flush the buffer. This 
assures that all the data is disk resident. 

1. The dataset is currently opened for output only. 

2. The dataset has not had an end-of-data written. 

3. The dataset is being written sequentially. 

4. The dataset has COS blocked dataset structure. 

5. The dataset 's DSP is managed by COS. 

SAVE does not close the dataset unless all of these conditions are true. 
SAVE applies to mass storage datasets; it is ignored for tape datasets. 
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Format: 



Location Result 



SAVE 



Operand 



pddtag 



pddtag Address of PDD macro call 



DELETE - DELETE PERMANENT DATASET 



The DELETE macro removes a permanent dataset from the Dataset Catalog, 
dataset must be accessed within a job with the maintenance permission 
control word and unique access before a DELETE may be issued. 



Format ; 



Lon 



Result 



DELETE 



9Pgr^r^d 



pddtag 



pddtag 



Address of PDD macro call 



ADJUST - ADJUST PERMANENT DATASET 

The ADJUST macro changes the size of a permanent dataset, that is, 
redefines end-of-data for the dataset. A dataset must be accessed with 
the write permission control word and unique access within a job before an 
ADJUST may be issued. 

If all of the following conditions are all true for the dataset, ADJUST 
makes a call to close the dataset and consequently to flush the buffer. 
This assures that all the data is disk resident. 

1. The dataset is currently opened for output only. 

2. The dataset has not had an end-of-data written. 

3. The dataset is being written sequentially. 

4. The dataset has COS blocked dataset structure. 

5. The dataset' s DSP is managed by COS. 

ADJUST does not close the dataset unless all of these conditions are true. 
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ADJUST applies to mass storage datsets only; it is ignored when used with 
tape datasets. 

Format : 



LQc^tj,Qn 



Mm^ 



ADJUST 



Operand 



pddtag 



pddtag Address of PDD macro call 
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CFT LINKAGE MACROS 



The CFT linkage macros handle subroutine linkage between CFT-compiled 
routines and CAL-assembled routines. 

These macros perform the following functions: 

• Generate code for calls, entries, and returns 

• Assign B and T registers 

• Fetch argument addresses 

These macros should be used to maintain compatibility across the 
various versions of CFT. 



CALL EXTERNAL ROUTINES 

The CALL and CALLV macros generate code to call external routines 
using the call-by-address or call-by-value convention. 



CALL - CALL EXTERNAL ROUTINE USING CALL-BY-ADDRESS CONVENTION 

The CALL macro builds a list of addresses for a call-by-address 
external routine. This first argument address is stored at entry 
point minus one, the second at entry point minus two, etc of the 
called routine. The total number of arguments is entered in A7. 



Format: 



Location 


Result 


Operand 




CALL 


name , {argument list) 
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name 



The name of the routine being called 



argument list 

The list of arguments to be passed (1 or more) . If more 
than one argument is passed, the arguments must be 
separated by commas. Each argument may be a literal, a 
word address symbol, or a register containing an address. 



CALLV - CALL EXTERNAL ROUTINE USING CALL-BY-VALUE CONVENTION 

The CALLV macro generates a call-by-value to an external routine. The 
arguments are passed in registers SI through S6 and must all be scalar 
quantities. The first argument is placed in SI, the second in S2, etc. 



Format: 



Location 


Result 


Operand 




CALLV 


name , {argument list) 



name 



The name of the routine being called 



argument list 

The list of arguments to be passed (1-6) . If more than one 
argument is passed, the arguments must be separated by 
commas. Each argument may be either a literal, a word 
address symbol, or a register symbol. S registers are 
loaded in numerical order. 



ENTER AND EXIT 

The ENTER and EXIT macros generate code for entries and returns using the 
call-by-address convention for normal CFT calls or call-by-value 
convention for library routines. 



ENTER - FORM A CFT CALLABLE ENTRY 

The ENTER macro generates code for a normal CFT call-by-address entry. 
It reserves space for parameter addresses, saves B and T registers, and 
sets up traceback linkage. As a option, it also sets up call-by-value 
entries for library routines. 
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Format : 



Location 


Result 


Operand 


name 


ENTER 


NB=nZ? , NT=nt , NP=np ,MODE=mode , 
TYPE=type ,'PBELOkD=n^sv ,coPYii>i=aopy , 

SYiKKED=shave ,ARGSlZE=sise 



ncune The name of the entry 

NB^Z? The number of B registers explicitly used by the routine, 
not including those that must be used by the calling 
sequence/traceback linkage. The default is 0. 

NT=^t The number of T registers explicitly used by the routine. 
The default is 0. 

NP^p The number of parameters to the routine. The default is 0. 

MODE=?«cde The kind of entry (USER or LIBRARY). The default is USER. 
LIBRARY mode is intended for special purpose use in $FTLIB 
routines. In LIBRARY mode, MB and NT must both be 0. 

TYPE=t2/pe The kind of calling sequence used to call name. The 
options are VALUE, ADDRESS, or BOTH. The default is 
ADDRESS. If BOTH is specified, the call-by-address entry 
precedes the call-by-value entry. If either BOTH or VALUE 
is specified, name must be the call-by-address name. The 
ENTER macro automatically appends a % to name for the 
call-by-value entry, type can be specified only in a 
LIBRARY mode entry. 

PRELOAD=^sy 

The number of parameters to be loaded into the S or V 
registers in a call-by-address entry. The default is np . 
PRELOAD can be specified only in a LIBRARY mode entry. If 
the first character of name is %, the arguments are loaded 
into V registers. Otherwise, they are loaded into S 
registers. V register arguments have two parts — the 
first is the base address of the argument, the second is 
the address of the memory increment between argument values 
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COPYIN=eopz/ 

If future calling sequences pass argument addresses in a 
different manner, CGPyiN=ON will generate code to copy 
the addresses into locations corresponding to the 
current calling sequence conventions. The default is 
COPYIN=OFF. 

SliABED=shave 

The name of a previous ENTER macro. If this parameter 
is specified, the previous entry and the current entry 
share storage space in which the B and T registers are 
saved. SHARED is intended for routines such as SIN and 
COS, which also share code sequences. 

hRGSlZE=siBe 

The size of the arguments. This parameter is only used 
in LIBRARY mode. If ARGSIZE=ONEWORD is specified, each 
argument is loaded into consecutive registers; that is, 
argument 1 is loaded in SI, argument 2 is loaded in S2, 
etc. If ARGSIZE=TWOWORD is specified, each argument is 
loaded into consecutive pairs of registers; that is, the 
first and second words of argument 1 are loaded into SI 
and S2, the first and second words of argument 2 are 
loaded into S3 and S4 , etc. The default is 
ARGSIZE=ONEWORD. Note that this parameter has meaning 
only when used with TYPE=ADDRESS or TYPE=BOTH. 



EXIT - RETURN FROM A ROUTINE 

The EXIT macro generates code to return program control from a routine 
to its caller. It restores those B or T registers used. 



Format: 



Location 



Result 



Operand 



EXIT 



NB=nZ? , NT=nt , NAME=naw7e , MODE=mode , KEEP= I ON I 

lOFFl 



Normally EXIT without any parameters is sufficient. The values from the 
most recently assembled (not necessarily executed) ENTER are used. 
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NB=w2? The number of B registers to restore; not including those 
used for call linkage 



NT=nt 



The number of T registers to restore 



likME=^ame The name of the entry corresponding to this exit 



MODE=mocie The same mode as that of the corresponding entry. The 

default is USER. If MODE=LIBRARY, EXIT assumes that (BO) 
has not been changed since the entry and that (Bl) may be 
restored from (Al) . 



KEEP=JON I 
I OFF I 



Requests that EXIT save and restore any scratch registers 

used. The default is KEEP=OFF. If KEEP=ON (or KEEP=YES) 
is specified, any scratch registers used by EXIT are 
restored to their original values. If KEEP=OFF (or 
KEEP=NO) is specified, the original values are not 
restored . 



REGISTER ASSIGNMENT 

The BREG and TREG macros assign values to symbols for use as B and T 
register names. 



BREG - ASSIGN SYMBOLS FOR B REGISTER NAMES 

The BREG macro assigns numerical values to symbols for use as B register 
names. It also checks that no more registers are used than are declared 
on the ENTER macro. The register names are assigned after any registers 
used in the call linkage. The first B register assigned is B2. 



Format: 



Location 



br 



Result 



BREG 



Operand 



bv 



A symbolic name used to designate a B register as in B.BR. 
BREG assigns bv a numerical value in sequence. 
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TREG - ASSIGN SYMBOLS FOR T REGISTER NAMES 

The TREG macro assigns numerical values to symbols for use as T register 
names. It also checks to see that no more registers are used than are 
declared on the ENTER macro. The register names are assigned after any 
registers used in the call linkage. The first T register assigned is TO, 



Format: 



Location 


Result 


Operand 


tr 


TREG 





tv 



A symbolic name used to designate a T register, as in 
T.TR. TREG assigns tr a numerical value in sequence. 



FETCH ARGUMENT ADDRESS 



ARGADD - FETCH ARGUMENT ADDRESS 



The ARGADD macro fetches an argument address (not a value) and places it 
in an A register. It is used only for call-by-address routines. 



NOTE 

The EXIT, BREG, TREG, and ARGADD macros can be used 
only in conjunction with an ENTER macro. 



Format : 



Location 


Result 


Operand 




ARGADD 


vesul t ,n , uSE^use 
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result The result register (A or S) to be loaded with the n^^ 
argument address 

n Argument number 

USE=wee The intermediate register used if result register is an S 
register 
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JOB USER AREA 



The user area of memory is assigned to one or more jobs. Figure A-1 
illustrates the user area of one job. The shaded area is not accessible 
to the user. 
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WgJCHLM- 



W@JCLFT- 



W@JCDSP. 



W@JCBFB 




W@JCFL- 



^(^ Table Area 



Job Communication Block 



user code 



Logical File Tables 



Dataset Parameter Area 



I/O Buffers 




> user 
field 



Figure A-1. User area of memory for a job 
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JOB TABLE AREA - JTA 

Each job has an area referred to as the Job Table Area (JTA) preceding 
the field defined for the user. A JTA is accessible to the operating 
system but not to the user. The format of a JTA is described in the COS 
Table Descriptions Internal Reference Manual, CRI publication SM-0045. 
The Job Table Area contains job-related information such as accounting 
data; a JXT pointer; sense switches; an area for saving B, T, and V 
register contents, control statement and logfile DSPs; a logfile buffer; 
a copy of the user's LFTs; and a Dataset Name Table (DNT) for each 
dataset used by the job. 



JOB COMMUNICATION BLOCK - JCB 

Following the JTA is a 128-word block referred to as the Job 
Communication Block (JCB) , The user accessible JCB contains a copy of 
the current control statement for the job and other job-related 
information. 

Figure A-2 illustrates an expansion of the JCB, 
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16 



16 



24 



32 



40 



48 



56 63 




70 

71 

72 

73 

74 

75 
76 

102 
103 



(Available for scratch space) 



CCI 



CPR 



JN 



I//////// 



LPP I //////// I 



HLM 



FL 



NPF 



BFB 



DSP 



NLE 



I/////////////////////// I 



LFT 



flags 



I /////////////////////////////////// I PNST I STRM 



'I/PSBC///////////////////////////////////////////////////////// 



OVL 



CRL 



ACNl 



ACN2 



I//////// 



PWDl 



PWD2 



PROM 



///////////////I 



PLEV 



I LEV 



CLEV 



//////////////////////////////////////////////////////////////// 



LDR 



//////////////////////////////////////////////////////////////// 
//////////////////////////////////////////////////////////////// 



Figure A-2. Job Communication Block (JCB) 



SR-0011 



A-3 



J-01 








8 


16 


24 


32 


40 


48 


56 


63 


118 


BOAT 


119 


BTIM 


120 

• 
• 
• 

127 


DIG 



Figure A-2. Job Coiranunication Block (JCB) (continued) 



Field 



JCCCI 



JCCPR 



Word 



5-15 



16-63 



Bits 



0-63 



0-63 



JCJN 


64 


0-55 


JCLPP 


65 


0-7 


JCHLM 


65 


16-39 


JCFL 


65 


40-63 


JCNPF 


66 


0-15 


JCBFB 


66 


16-39 


JCDSP 


66 


40-63 


JCNLE 


67 


0-15 


JCLFT 


67 


40-63 


Flags : 
JCSIM 
JCCSDB 
JCBP 
JCMRF 


68 


0-12 



1 

2 

3 


JCIOAC 




4 



Description 

Control statement image packed 8 
characters per word 

Control statement parameters , 
expanded to 2 words per parameter 

Job name; bits 56-63 must be 

Lines per page 

High limit of user code 

Current field length 

Number of physical buffers and 
datasets 

Base address of I/O buffers 

Base address of DSP area 

Number of entries in LFT 

Base of LFT 



Simulator flag 

CSP debug flag 

JOB statement breakpoint (BP) flag 

Memory request flag. If set, dynamic 

field management by CAL, LDR, etc. is 

not allowed. 

I/O area current status flag : 

User's I/O area is unlocked 

1 User's I/O area is locked 
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Field 



Word 



Bits 



Flags (continued) : 




JCIOAP 


68 


5 


JCIA 




6 


JCCHG 




7 


JCJBS 




8 


JCCSIM 




9 


JCDLIT ^ 




10 


JCRPRN 




11 


JCVSEP 




12 


JCPNST 


68 


48-5 


JCSTRM 


68 


56-6 



JCEFI 



69 



Description 



I/O area previous status flag: 

User's I/O area is unlocked 

1 User's I/O area is locked 
Interactive flag 

Execute CHARGES utility for trailer 

message 

JOB statement flag (if set, JOB 

statement just processed) 

Flag is set when CRAY-1 simulator is 

running. 

Display literal delimiters in control 

statement crack. 

Retain level 1 parentheses 

Last character was valid separator. 

Parentheses nesting level for current 
control statement 

Statement termination for current 
control statement 

Enable floating interrupt flag; used 
by $FTLIB math routines to reset 
floating-point interrupt flag 



JCOVL 


69 




1 


JCSBC 


69 




2 


JCCRL 


70 




0-63 


JCCRLS 


70 




32-63 


JCACN 


71- 


72 


0-63 


JCACNl 


71 




0-63 


JCACN2 


72 




0-55 



Overlay flag 

SBCA flag 

COS revision level 

COS revision number 
1 through 15 character account number 

Characters 1 through 8 of account 

number 

Characters 9 through 15 of account 

number 



JCPWD 



JCPWDl 
JCPWD2 



73-74 

73 
74 



0-63 

0-63 
0-55 



1 through 15 character password 

Characters 1 through 8 of password 
Characters 9 through 15 of password 
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Field 



Word 



Bits 



Description 



JCPROM 



75 



0-63 



JCPLEV 


76 


16-31 


JCILEV 


76 


32-47 


JCCLEV 


76 


48-63 


JCLDR 


102 


0-63 


JCBDAT 


118 


0-63 


JCBTIM 


119 


0-63 


JCDIG 


120-127 


0-63 



Current user job interactive prompt, 
1-8 ASCII characters, left-justified, 
zero-filled. 64 bits of binary 
zeroes disables user job prompt. Set 
to system default at beginning of 
each job step. 

Current procedure nesting level 

Current iterative nesting level 

Current conditional nesting level 

Unsatisfied externals 

Date of absolute load module 
generation 

Time of absolute load module 
generation 

Reserved for diagnostics 



LOGICAL FILE TABLE - LFT 

The Logical File Table contains a 2-word entry for each dataset name and 
each alias for a dataset. Each entry points to the DSP for a dataset. 
Figure A-3 illustrates an LFT for a dataset. 
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Field 

LFDN 

LFDSP 



DN 



////////////////////////////////////////I 



DSP 



Figure A-3. Logical File Table (LFT) entry 
Word Bits Description 

0-55 Dataset name or alias 

1 40-63 DSP address 



56 



63 



/////// 
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DATASET PARAMETER AREA - DSP 



Information concerning the status of a particular dataset and location of 
the I/O buffer for the dataset is maintained in the Dataset Parameter 
Area (DSP) of the user field. The DSP is illustrated in figure A-4. 
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t 



ERR 



/////////I IPB I 



UEOF 



//I RBC I OBP I 



BIO 





1 

2 

3 

r\//////////////\ 

5 

6 

7_J<J BF I BUBCI 



8 



TPD 



16 



TPF 



17 

I 

is" 

19 
20 
21 
22 
23 



BSY 



STS 



DN 



I/////// 



IM BFI l/Ti flags r 



FRST 



IBN 



IN 



OBN 



OUT 



TBN 



LMT 



flags I 



PFI 



PRI 



RCW 



LPW 



BWC 



BWA 



BER 



TM 

reserved 

for use by 

TIO 



TPS 



TPB 



TPV 



b I ///////////////////////////////////////////I 



J^ 



MTF 



CT 



RF 



///I 



MBS 



RS 



BFBO I CS I ////I 



FBL 



BFBA 



LPBL I ////////////////////////////////// I 



BLBL 



Reserved for logical I/O 



EEC 



///////////////////////////////////////////////////// 



/////////// 1 flags 



RECL 



NXRC 



Figure A-4. Dataset Parameter Area (DSP) 



Field 


Word 


Bits 


Description 


DPDN 





0-55 


Dataset name 


DPBSY 


1 





Busy flag, circular I/O 

Not busy 

1 Busy 
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Field 

DPERR 

DPEOI 

DPENX 
DPEOP 
DPEPD 
DPEBN 
DPEDE 
DPEHE 
DPERW 

DPEPT 
DPELE 

DPEEP 

DPSTS 



Word 



Bits 



1-12 



2 
3 
4 
5 
6 
7 
8 

9 

10 
11 
12 

14-15 



DPBFI 



16-24 



Description 

Error flags; 

End of data on read; write past 

allocated disk space on write 

Dataset does not exist 

Dataset not open 

Invalid processing direction 

Block number error 

Unrecovered data error 

Unrecovered hardware error 

Attempted read after write or 

past EOD 

Dataset prematurely terminated 

Unrecovered logical data error 

Reserved 

Extended error (see DPEEC) 

Status: 

00 Closed 

01 Open for input (I) 

10 Open for output (O) 

11 Open for I/O 

Blank compression character in ASCII 
(BFI=777g implies no compression) 



Flags: 
DPABD 
DPBDF 
DPTCS 
DPTP 
DPTRAN 

DPIA 

DPMEM 

DPRDM 



DPUDS 



28- 


■39 


28 




29 




30- 


-31 


32- 


•33 


34 




35 




36 




37 





38 



DPEND 




39 


DPFRST 


1 


40-63 


DPIPB 


2 


10-15 



Accept bad data flag 

Bad data flag 

Tape dataset character set 

Tape dataset (online/staged) 

Transparent mode for interactive 

dataset 

Dataset is interactive 

Dataset is memory resident 

Random dataset flag: 

Sequential dataset 

1 Random dataset 
Undefined dataset structure: 

COS blocked dataset structure 

1 Undefined dataset structure 
Write end-of-data flag 

Address of first word of buffer 

Bit position in current input word 
(character I/O only) 
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Field 



Word 



Bits 



Description 



DPIBN 



16-39 Block number, read request. System 
reads from block number until buffer 
is filled. DPIBN is then set to the 
next block number. 



DPIN 


2 


40-63 


DPRBC 


3 


3-9 


DPOBP 


3 


10-15 



DPOBN 



DPLMT 



16-39 



DPOUT 


3 


40-63 


DPUEOF 


4 





DPTBN 


4 


16-39 



40-63 



Address of current input word 

Remaining blank count 

Bit position in current output word 
(character I/O only) 

Block number, write request. System 
writes from block number until buffer 
is empty. The next block number is 
then in DPOBN. 

Address of current output word 

Uncleared end-of-file (EOF) 

Temporary block number; used by 
random I/O for last block read. 

Address of last word+1 of buffer . 
LMT minus FRST defines buffer size. 



Flags: 
DPEOR 
DPEOF 
DPEOD 
DPRW 



I DPPFI 



DPPRI 



DPRCW 



0-4 



2 

3 

4 



5-24 



25-39 



40-63 



EOR flag 
EOF flag 
EOD flag 
Previous operation read/write flag: 

Read 

1 Write 

Previous file index; backward index 
to block containing previous EOF. 

Previous record index; backward index 
to block containing previous EOR. 

Control word address: 

Previous RCW address if in write 

mode 

Next RCW if in read mode 
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Field 



Word 



Bits 



Description 



DPLPW 



DPBIO 



0-63 



DPBER 
DPBF 



1 
2-9 



Last partial word; used for character 
mode I/O. 

Buffered I/O busy: 

Buffered I/O operation 
complete 

1 Buffered I/O operation 
incomplete 

Buffered I/O error flag 

Function code: 



DPBPD 



000 Read partial 

010 Read record 

040 Write partial 

050 Write record 

052 Write end-of-file 

056 Write end-of-data 

Processing direction: 



Read 

1 Write 



DPBEO 



6-9 



Termination condition: 



DPBUBC 



DPBWC 



10-15 



16-39 



DPBWA 


7 


40-63 


DPTM 


8-15 
8 


0-63 
0-63 




9 

10 

10 


0-63 

16-39 

40-63 



00 Partial 

10 Record 

12 File, write only 

16 Dataset, write only 

Unused bit count; must be specified 
on a write record request. Value 
returned on a read request. 

Word count; number of words at DPBWA 
to read or write. Field contains 
actual number of words read when 
request is completed. 

Word address of user data area 

Used by TIO as follows: 
Saved word W@DPPRI 
Saved A2 in WB30 
$RWDP/$WWDP return address 
$RWDP/$WWDP first word address (FWA) 
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Field 



Word 



DPTM (continued) 




11 




11 




12 




12 




12 




12 




13 




13 




13 




14 




14 




14 




15 


DPTPS 


16 


DPTPB 


16 


DPTPV 


16 


DPTPD 


17 


DPTPF 


17 


DPMFT 


17 


DPCT 


18 



Bits Description 

16-39 WB30/$WEOF return address 

40-63 $WEOD return address 

0-7 JTA length/lOOOg when registers 

are saved 

8-15 Bits 0-7 of RBLK/WBLK A5 

16-39 (B.ZE) 

40-63 RBLK/WBLK BO 

16-39 DNT address 

40-63 (A7) JXT address 

0-63 RBLK/WBLK S5 during task recall 

0-15 Bits 8-23 of RBLK/WBLK A5 

16-39 RBLK/WBLK A2 

40-63 RBLK/WBLK A3 

0-63 RBLK/WBLK S6 

0-15 Online tape status 

16-39 Tape maximum block size in bytes 

40-63 Tape pointer to label definition table 

0-1 Tape density 

2^3 Tape format 

48-63 Maintenance test field (used by DQM) 

0-3 Conversion type; nonzero if run-time 
data and record format conversion 
selected. 

DPCTNONE=0 No conversion 
DPCTIBM=1 IBM format data 



DPRF 


18 


4-11 


Record format 
DPRFNONE=0 
DPRFIU=1 
DPRFIF=2 
DPRFIFB=3 
DPRFIV=4 
DPRFIVB=5 

DPRFIVBS=6 


(if DPCT nonzero) 

None 

IBM undefined format 

IBM fixed format 

IBM fixed blocked format 

IBM variable format 

IBM variable blocked 

format 

IBM variable block span 

format 


DPMBS 


18 


16-39 


Maximum block 


size 


DPRS 


18 


40-63 


Record length 
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Field 

DPBFBO 

DPCS 



DPDIR 
DPUFMT 

DPRECL 
DPNXRC 



Word 

19 

19 



23 



23 



Bits 

0-5 

6-11 



DPBFBL 


19 


16-39 


DPBFBA 


19 


40-63 


DPLPBL 


20 


0-5 


DPBLBL 


20 


40-63 


Reserved 


21 


0-63 


DPEEC 


22 


0-11 


Flags: 


23 


12-15 


DPDEL 




12 


DPBLNK 




13 



14 
15 

16-39 
40-63 



Description 

User data area current bit offset 

Character set (if DPCT nonzero) : 
DPCSA=0 ASCII, 8 bits/character 
DPCSE=1 EBCDIC, 8 bits/character 

User data area current bit length 

User data area current address 

Last partial word bit length 

Current tape block bit length 

Reserved for logical I/O 

Error code if DPEEP is set; 
correspond to EXP abort codes. 



FORTRAN file status: 

Keep 

1 Delete 

FORTRAN numeric input blank 
conversion: 

Null 

1 Zero 

FORTRAN direct access flag 
FORTRAN unformatted I/O flag 

FORTRAN direct access record length 
(in number of characters) 

FORTRAN direct access next record 
number 
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PERMANENT DATASET DEFINITION TABLE - PDD 

The PDD is a parameter list that gives input to the Permanent Dataset 
Manager. The contents of PDD are illustrated in figure A-5. 



TPD 



TPL 
TPM 



flags DTR SMT 

/ 8\ / 16 



7M 



24 



32 



40 



48 



\^y^m//\ 



LSD 



ST 



TP TCS EXO 



DN 



PDNl 



PDN2 



ID 



USR 



TXT 



FM 



RT 



OJB 



SID 



DID 



DC 



TID 



SF 



m TXL I flags I 



FL 



TL 



ENT 



RD 



WT 



MN 



JCN 



CL 



56 



63 



FC 



I//////// 



\ //////// 



\ //////// 



ED 



\ //////// 



JSQ 



PR 



\ //////// 



\ //////// 



JSP I TPF 



JCR 



OLM 



I RJST I IJSP 



1^ I A//////IUPC TPB 



TPV 



\_^ 



k^Ti 



I IDC//////////////////////////////////////////////////// 



TPP TP2 TPH 



RGl 



RG9 



//////////////////////////////////////////////////////////////// 



///////////////////////////////////I 



FPP 



FEN 



ACS 



DSZ 



OJSQ 



CRT 



Figure A-5. Permanent Dataset Definition Table (PDD) 
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16 



24 



32 



40 



48 



56 



63 



27 
28 
29 
30 



ACT 



TDM 
MOD 



SSC I TXC I 



MML 



I///////////////////////////////// 



Figure A-5. Permanent Dataset Definition Table (PDD) (continued) 



Field 



Word 



Flags: 





PMSG 




PMERR 




PMWAIT 




PMNRLS 




PMAQR 




PMTP 





PMTCS 





PMEXO 





PMDTR 





PMSMT 





PMLSD 






PMST 



Bits Description 
0-4 

Normal completion message suppression 
indicator 

1 Error message suppression indicator 

2 WAIT flag for a disposed dataset 

3 No release of dataset on DISPOSE 

4 Acquire flag for accounting 

5-6 Tape dataset (online/staged) 

7-8 Tape dataset character set 

9-10 Execute only 

11 Update dump-time on PDSDUMP access 

12 Submit flag 

16-39 Temporary SDT address for load 
input/output 

40-51 Return status; the codes are defined 
in Appendix F. 



PMFC 





52-63 


Function code 


PMDN 


1 


0-55 


Local dataset name 


PMPDN 


2-3 


0-63 


Permanent dataset name 


PMPDNl 


2 


0-63 


Characters 1-8 


PMPDN2 


3 


0-55 


Characters 9-15 



PMID 



0-63 



User identification 
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Field 



PMUSR 



Word 



5-6 



PMUSRl 


5 


PMUSR2 


6 


PMTXT 


7 


PMFM 


7 



Bits 

0-63 

0-63 
0-55 

0-23 

24-39 



PMRT 


7 


40-51 


PMED 


7 


52-63 


PMOJB 


8 


0-55 


PMSID 


9 


0-15 


PMDID 


9 


16-31 


PMDC 


9 


32-47 



PMJSQ 


9 


48-63 


PMTID 


10 


0-63 


PMSF 


11 


0-63 


PMUQ 


12 





PMENT 


12 


1 


PMIR 


12 


2 


PMTXL 


12 


3-10 



Description 

User number 

Characters 1-8 
Characters 9-15 

Address of optional text field 

Format designator (two characters) : 

FMCD=CD Character/deblocked 

FMCB=CB Character /blocked 

FMBD=BD Binary/deblocked 

FMBB=BB Binary/blocked 

Retention period; 0-4095 days 

Edition number (0-4095) 

Originating job name 

Source ID; 2 characters. 

Destination ID; 2 characters. 

Disposition code; 2 characters. 

DCIN=IN Job dataset 

DCST=ST Dataset to be staged 

DCSC=SC Scratch dataset 

DCPR=PR Print dataset 

DCPU=PU Punch dataset 

DCPT=PT Plot dataset 

DCMT=MT Magnetic tape dataset 

Job sequence number 

Terminal ID; 1-8 characters. 

Special forms 

Unique access required 

Enter in System Directory 

Immediate reply requested 

Number of words of text 
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Field 



Word 



Bits 



Description 



PMNRR 



12 



11 



PMINIT 


12 


12 


PMIA 


12 


13 


PMDFR 


12 


14 


PMNA 


12 


15 



PMFL 


12 


16-31 


PMTL 


12 


32-55 


PMPR 


12 


56-63 


PMRD 


13 


0-63 


PMWT 


14 


0-63 


PMMN 


15 


0-63 


PMJCN 


16 


0-55 


PMCL 


17 


0-55 


PMSYS 


18 





PMJSP 


18 


1-8 


PMJCR 


18 


9-24 


PMOLM 


18 


25-48 


PMRJST 


18 


49-55 


PMIJSP 


18 


56-63 


PMTPD 


19 


0-1 


PMTPL 


19 


2-4 


PMTPF 


19 


5-6 


PMTPC 


19 


15 



Job rerun flag; set if job cannot be 
rerun (input entries only) . 

Job initiate flag; set if job has 
been initiated. 

Interactive flag 

Deferred disposition indicator 

No abort flag. If set, processing 
continues even if an error is 
encountered. 

Field length/512 (input datasets only) 

Time limit (input datasets) 

Priority (input datasets) 

Read permission control word 

Write permission control word 

Maintenance permission control word 

Job class name 

CL parameter from JOB statement 

System job 

JOB statement priority 

Job class rank 

Size of $OUT in 512-word block 

Job status flag 

Original job card priority 

Tape density 

Tape label type 

Tape format 

Tape cataloged dataset 
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Field 



Word 



Bits 



PMTPB 


19 


16-39 


PMTPV 


19 


40-63 


PMTPM 


20 





PMTPP 


20 


1-3 


PMTP2 


20 


4 


PMTPH 


20 


5 


PMIDC 


20 


6-8 


PMRGl 


21 


0-63 


PMRG9 


22 


0-63 


PMFPE 


24 


36-63 


PMFPP 


24 


36-59 


PMFEN 


24 


60-63 



PMACS 



PMDSZ 



PMOJSQ 
PMCRT 

PMACT 

PMTDM 

PMMOD 



25 



25 



25 
26 

27 

28 

29 



0-15 



16-47 



48-63 
0-63 

0-63 

0-63 

0-63 



PMSSC 


30 


0-7 


PMTXC 


30 


8-15 


PMMML 


30 


16-27 



Description 

Tape maximum block size in bytes 

Tape pointer to label definition table 

Tape online maintenance access 

Tape parallel device count 

Tape second device assignment 

Tape hold assigned device 

Tape initial desposition code 

First word of resource generic names 

Second word of resource generic names 

First DSC page/entry for dataset 

First DSC page for dataset 
First entry for dataset 

Number of accesses (load saved 
datasets only) 

Size of dataset as reflected by DSC 
DAT bodies (used only when a pseudo 
access is performed during the 
recovery of rolled jobs) 

Originating job sequence number 

Creation time in cycles (load request 
only) 

Time of last access in cycles (load 
request only) 

Time of last dump in cycles (load 
request only) 

Time of last modification in cycles 
(load request only) 

Station slot word length 

Text field word length 

Interactive maximum message length 
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BEGIN CODE EXECUTION TABLE - BGN 

The BGN table specifies necessary parameters to begin execution of code 
loaded into the user area by the Control Statement Processor. Figure A-6 
illustrates the BGN. 



PSF 







8 



16 



24 



32 



40 



48 



56 



63 



BP. 



M^ 



I////////////// 



PRGL 



PRWC 



1 //////////////////////////////////////////////////////////////// 



I ////////////////////////////////////// I 



ENT 



Field 



Figure A-6. Begin Code Execution Table (BGN) 
Word Bits Description 

Preset value flag 



BGPSF 








BGPRGL 





16-39 


BGPRWC 





40-63 


BGBP 


2 





BGENT 


2 


40-63 



Total program length including blank 
common 

Program word count 

Breakpoint flag 

Program entry point P-address 
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DATASET DEFINITION LIST - DDL 

A Dataset Definition List in the user field must accompany any create DNT 
(F$DNT) request. The DDL is illustrated in figure A-7. 



8 16 24 32 40 48 


56 63 


DN 


1 //////// 


LDV 


flags 1 BFI 1 /////////////////////// 1 


SZ 


///////////////I DNT I////////I 


BFZ (BSZ) 


///////////////////////////////////////////////I 


DC 


///////////////////////////////////////I 


LM 



Field 



DDUDS 



DDNFE 



DDSTAT 

DDMR 
DDIA 
DDTRAN 



DDBFI 



Figure A~7. Dataset Definition List (DDL) 
Word Bits Description 



DDDN 





0-55 


Dataset name 


DDLDV 


1 


0-63 


Logical device name 


Flags: 
DDRDM 


2 


0-6 



Random dataset flag: 

Sequential 

1 Random 



7-15 



Undefined dataset structure: 

COS blocked dataset structure 

1 Undefined structure 
Return error if dataset does not 
exist. Register SO returned nonzero 
if DNT does not exist; no DNT is 
created. 

Request dataset statistics; ignored 
unless DDNFE=1 (see DDDNT) 
Dataset is to be memory resident 
Interactive type dataset 
Transparent mode for interactive 
dataset 

Blank field indicator for character 
I/O 



OOO3 
4008 



= 400 

> 400 



BFI=I@BFI 

BFI=user specified ASCII 

character 

BFI^^OOO 

Blank compression 

disabled 
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Field 



Word 



DDSZ 


2 


40-63 


DDDNT 


3 


16-39 


DDBFZ 


3 


49-63 


DDBSZ 


3 


49-63 



DDDC 



DDLM 



Bits Description 

Dataset size in 512-word blocks 

Address of DNT image returned by 
F$DNT when DDNFE=1 and DDSTAT=1 

Buffer size in 512-word blocks 

Alternate name for DDBFZ to match 
$SYSTXT name 

48-63 Disposition code (two characters) : 

DCIN=IN Job dataset 

DCST=ST Staged permanent dataset 

DCSC=SC Scratch dataset 

DCPR=PR Print dataset 

DCPT=PT Plot dataset 

DCPU=PU Punch dataset 

DCMT=MT Magnetic tape dataset 

40-63 Dataset size limit in 512-word blocks 
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OPEN DATASET NAME TABLE - ODN 

A 2-word Open Dataset Name Table (ODN) is generated in the user field the 
first time an OPEN of the specified dataset is encountered. Figure A-8 
illustrates the ODN. 







8 



16 



24 



32 



40 



48 



56 



63 



flags 



? 



DN 



\ //////// 



/I ^i/ I//I 



LDT 



I /////I 



DSP 



Figure A-8. Open Dataset Name Table (ODN) 



Field 

ODDN 

Flags: 

ODV^ 
ODM§ 
ODS§ 
ODH§ 

ODLDT§ 

ODDSP 



Word 



1 



Bits 

0-55 

1-4 

1 
2 
3 
4 

8-32 

40-63 



Description 
Dataset name 



Close volume 

Open for 'MOD' 

Close/open with saved position 

Hold resources 

LDT address 

DSP pointer : 

Negative Negative offset from 

beginning of DSPs 
Positive Offset from user base 

address 



§ Deferred implementation 
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OPTION TABLE - OPT 

The Option Table (OPT) is used for F$OPT calls. Figure A-9 illustrates 
the OPT. 







8 



16 



24 



32 



40 



48 



56 63 







OPLPP 



1 J////////////////////////////////////////////////////////////// 



OPSTAT 



Field 



Word 



OPLPP 
OPSTAT 1 



Figure A-9. Option Table (OPT) 

Bits Description 

0-63 Page length 

DSP address 
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JCL BLOCK INFORMATION TABLE - JBI 



The 1-word JCL Block Information Table (JBI) is generated in the user 
field and has two formats: one for conditional information (figure A-10) 
and the other for interative information (figure A-11) . 



Conditional block information: 



8 



16 



24 



32 



40 



48 



56 



EXC-M ///////////// 



LLEV 



PLEV 



LEVL 



Field 



JBEXC 





JBLLEV 


16-31 


JBPLEV 


32-47 


JBLEVL 


48-63 



63 



Figure A-10. JCL conditional block information 

Bits Description 

Conditional sequence is in execution 

Conditional is contained in this iterative 
nesting level 

Conditional is contained in this procedure level 

Current conditional nesting level 



Iterative block information: 
8 16 



Field 



24 



32 



40 



48 



///////I 



CNT 



PLEV 



JBCNT 


8-31 


JBPLEV 


32-47 


JBLEVL 


48-63 



56 



63 



LEVL 



Figure A-11. JCL iterative block information 
Bits Description 

Iteration count 

Iterative is contained in this procedure level 

Current iterative nesting level 
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JCL SYMBOL TABLE - JST 



The 4-word JCL Symbol Table (JST) is generated in the user field and 
contains information about system and user symbols. See figure A-12. 



CRE, 



N: 



8 



16 



24 



32 



40 



48 



56 



63 



'I////////////////////////////////////////////////////////////// 



SN 



flags I /////// 1 TYPE I ////////////////// 1 



LEVL 



/////////////////I 



LEN 



I///// 



VAL 



Field 



JSCRE 



JSTYPE 



Figure A-12. JCL Symbol Table (JST) 



Word 



JSSN 


1 


Flags: 


2 


JSLCX: 




J SCON 




JSSRS 




JSUSR 




JSSYS 





Bits 



0-63 

0-4 



1 

2 

3 

4 

10-15 



JSLEVL 


2 


40-63 


JSLEN 


3 


12-35 


JSVAL 


3 


40-63 



Description 

Create if not found. Available only 
for system use. 

Symbol name 



Local or global. If set, symbol is 

procedure local. 

Constant or variable. If set, symbol 

is constant. 

System reserved. If set, the symbol 

name is reserved by the system. 

User settable. If set, symbol may be 

modified by the job. 

System settable. If set, the symbol 

may be modified by COS. 

One of the following symbol types: 

SYMTUDF 00 Undefined - no type 
SYMTBOO 01 Boolean - logical 
SYMTINT 02 Decimal integer 
SYMTLIT 03 ASCII literal; 1-8 
characters. 

Procedure definition level 

Length of value 

Base of value buffer 
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LABEL DEFINITION TABLE ~ LPT 

The following conditions must be met for constructing a Label Definition 
Table (LDT) : 

• The table order must include an LDT header, volume entry, header 1 
entry, and header 2 entry. 

• The length value for either header 1 or header 2 must be at least 
the defined length of the respective entry. 

• The length value for Volume 1 must be at least the length of the 
entire first VSN. 



Header : 



16 



24 



32 



40 



48 



56 



63 



TN 



I /////////////////////// I 



TL 



CT I/////////////////////////////////// I 



DNT 



///////////////I 



VIB 



HIB 



///////////////I 



H2B 



I //////////////////////// 



Figure A-13. LDT header 



Field 



Word 



Bits 



LDTN 





0-23 


LDTL 





48-63 


LDCT 


1 


0-3 


LDDNT 


1 


40-63 


LDVIB 


2 


16-39 



LDHIB 



LDH2B 



40-63 



16-39 



Description 

Table name 

Table length (variable) 

Conversion type 

Dataset name table (DNT) pointer 

Offset of volume 1 entry, relative to 
LDT base 

Offset of header 1 entry, relative to 
LDT base 

Offset of header 2 entry, relative to 
LDT base 
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Volume 1 entry: 

8 



1 

2 



16 



24 



32 



40 



48 



56 



63 





VOLl 




I///////////////I VLIL 


VSNL 


1 


CVN 


1//////////////////////////////// 






VSNl 


1 //////////////// 



Field 

LDVOLl 

LDVLIL 

LDVSNL 

LDCVN 

LDVSNl 



Figure A-14. 

Word Bits 

0-31 

48-63 

1 0-15 

1 16-31 

2 0-47 



LDT volume 1 entry 
Description 

Volume 1 label identifier 
Volume 1 length 
Number of VSNs in list 
Current VSN ordinal 
Beginning VSN 



Header 1 entry: 

8 



1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 



16 



24 



32 



40 



48 



56 



63 



HDRl 




I///////////////I HRIL 


FIDl 


FID2 


FID3 


FID4 


FIDS 


FID6 




1//////////////////////////////// 


FSEC 




1 CSEC 


FSEQ 




1//////////////////////////////// 


GEN 




I//////////////I GVN 




CDT 


1 //////////////// 




XDT 


1 DRT 




BLK 


1 //////////////// 




SET 


1 //////////////// 



Figure A-15. LDT header 1 entry 
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Field 

LDHDRl 

LDHRIL 

LDFIDl 

LDFID2 

LDFID3 

LDFID4 

LDFID5 

LDFID6 

LDFSEC 

LDCSEC 

LDFSEQ 

LDGEN 

LDGVN 

LDCDT 

Lix:sp 

LDCYR 
LDCDY 

LDXDT 
LDXSP 
LDXYR 
LDXDY 

LDRT 

LDBLK 

LDSET 



Word 





1 

2 

3 

4 

5 

6 

7 

7 

8 

9 

9 

10 



11 
11 
11 
11 

11 

12 

13 



Bits 

0-31 

48-63 

0-63 

0-63 

0-63 

0-63 

0-63 

0-31 

0-31 

32-63 

0-31 

0-31 

48-63 

0-47 
0-7 
8-23 
24-47 

0-47 
0-7 
8-23 
24-47 

48-63 

0-47 

0-47 



Description 

Header 1 label identifier 

Header 1 length 

Characters 1-8 of file identifier 

Characters 9-16 of file identifier 

Characters 17-24 of file identifier 

Characters 25-32 of file identifier 

Characters 33-40 of file identifier 

Characters 41-44 of file identifier 

File section number 

Current file (volume) section number 

File sequence number 

Generation number 

Generation version number 

Creation date 
Space 
Year 
Day 

Expiration date 
Space 
Year 
Day 

Retention period 

Block count 

File set identifier 
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Header 2 entry: 

8 



LDBA 



16 



24 



32 



40 



48 



56 



63 



HDR2 



HR2L 



FMT 



BA 



I//////////////////////////////////////////////// 



BFO 



//////////////////////////////////////////////// 



BL 



I //////////////////////// 



RL 



//////////////////////// 







Figure A-16 


Field 


word 


Bits 


LDHDR2 





0-31 


LDHR2L 





48-63 


LDFMT 


1 


0-7 



8-15 



LDT header 2 entry 

Description 

Header 2 label identifier 

Header 2 length 

Record format. Valid values: 
F, V, U IBM label types 
F, D, S ANSI label types 

Block attributes, IBM standard label: 
B Blocked records 
S Spanned records 
R Blocked and spanned records 
' ' No blocked or spanned records 



LDBFO 


2 


0-15 


Buffer offset 


LDBL 


3 


0-39 


Block length in bytes 


LDRL 


4 


0-39 


Record length in bytes 
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CHARACTER SET B 



This appendix describes the 128 control and graphic characters comprising 
the ASCII character set. Those numbers, letters, and special characters 
that form the CRAY-1 FORTRAN character set are identified by the appearance 
of the letter C in the fourth column. All other characters are members of 
the auxiliary character set. The letter A in the fourth column of the 
table indicates those characters belonging to the ANSI FORTRAN character 
set. Note that all control characters are grouped on the first page. 
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CONTROL 
CHARACTER 



ASCII ASCII FORTRAN 
OCTAL PUNCHED-CARD (A=ANSI) 
CODE CODE (C=CRAY) 



DESCRIPTION 



NUL 000 12-0-9-8-1 

SOH 001 12-9-1 

STX 002 12-9-2 

ETX 003 12-9-3 

EOT 004 9-7 

ENQ 005 0-9-8-5 

ACK 006 0-9-8-6 

BEL 007 0-9-8-7 

BS 010 11-9-6 

HT Oil 12-9-5 

LF 012 0-9-5 

VT 013 12-9-8-3 

FF 014 12-9-8-4 

CR 015 12-9-8-5 

50 016 12-9-8-6 

51 017 12-9-8-7 
DLE 020 12-11-9-8-1 
DCl 021 11-9-1 

DC2 022 11-9-2 

DC3 023 11-9-3 

DC4 024 9-8-4 

NAK 025 9-8-5 

SYN 026 9-2 

ETB 027 0-9-6 

CAN 030 11-9-8 

EM 031 11-9-8-1 

SUB 032 9-8-7 

ESC 033 0-9-7 

FS 034 11-9-8-4 

GS 035 11-9-8-5 

RS 036 11-9-8-6 

US 037 11-9-8-7 

DEL 177 12-9-7 



Null 

Start of heading (CC) 

Start of text (CC) 

End of text (CC) 

End of transmission (CC) 

Enquiry (CC) 

Acknowledge (CC) 

Bell (audible or attention signal) 

Backspace (FE) 

Horizontal tabulation (FE) 

Line feed (FE) 

Vertical tabulation (FE) 

Form feed (FE) 

Carriage return (FE) 

Shift out 

Shift in 

Data link escape (CC) 

Device control 1 

Device control 2 

Device control 3 

Device control 4 (stop) 

Negative acknowledge (CC) 

Synchronous idle (CC) 

End of transmission block (CC) 

Cancel 

End of medium 

Substitute 

Escape 

File separator (IS) 

Group separator (IS) 

Record separator (IS) 

Unit separator (IS) 

Delete 



Legend: CC - Communication control 
FE - Format effector 
IS - Information separator 
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GRAPHIC 
HARACTER 


ASCII 

OCTAL 

CODE 


ASCII 

PUNCHED-CARD 

CODE 


FORTRAN 
(A=ANSI) 
(C=CRAY) 


DESCRIPTION 




(Space) 


040 


(None) 


A,C 


Space (blank) 




j 


041 


12-8-7 




Exclamation point 




•1 


042 


8-7 


C 


Quotation marks (diaeresis) 




# 


043 


8-3 




Number sign 




$ 


044 


11-8-3 


A,C 


Dollar sign (currency symbol) 




% 


045 


0-8-4 




Percent 




& 


046 


12 




Ampersand 




1 


047 


8-5 


C, 


Apostrophe (closing single quotation 


mark) 


( 


050 


12-8-5 


A,C 


Opening (left) parenthesis 




) 


051 


11-8-5 


A,C 


Closing (right) parenthesis 




* 


052 


11-8-4 


A,C 


Asterisk 




+ 


053 


12-8-6 


A,C 


Plus 




1 


054 


0-8-3 


A,C 


Comma (cedilla) 




- 


055 


11 


A,C 


Minus (hyphen) 




. 


056 


12-8-3 


A,C 


Period (decimal point) 




/ 


057 


0-1 


A,C 


Slant (slash, virgule) 







060 





A,C 


Zero 




1 


061 


1 


A,C 


One 




2 


062 


2 


A,C 


Two 




3 


063 


3 


A,C 


Three 




4 


064 


4 


A,C 


Four 




5 


065 


5 


A,C 


Five 




6 


066 


6 


A,C 


Six 




7 


067 


7 


A,C 


Seven 




8 


070 


8 


A,C 


Eight 




9 


071 


9 


A,C 


Nine 




: 


072 


8-2 


C 


Colon 




/ 


073 


11-8-6 




Semicolon 




< 


074 


12-8-4 




Less than 




= 


075 


8-6 


A,C 


Equal 




> 


076 


0-8-6 




Greater than 




7 


077 


0-8-7 




Question mark 
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GRAPHIC 
CHARACTER 



ASCII ASCII FORTRAN 

OCTAL PUNCHED-CARD (A=ANSI) 

CODE CODE (C=CRAY) 



DESCRIPTION 



(3 
A 
B 
C 
D 
E 
F 
G 
H 
I 
J 
K 
L 
M 
N 

P 

Q 
R 
S 
T 
U 
V 
W 
X 
Y 
Z 



100 
101 
102 
103 
104 
105 
106 
107 
110 
111 
112 
113 
114 
115 
116 
117 
120 
121 
122 
123 
124 
125 
126 
127 
130 
131 
132 
133 
134 
135 
136 
137 



8-4 

12-1 

12-2 

12-3 

12-4 

12-5 

12-6 

12-7 

12-8 

12-9 

11-1 

11-2 

11-3 

11-4 

11-5 

11-6 

11-7 

11-8 

11-9 

0-2 

0-3 

0-4 

0-5 

0-6 

0-7 

0-8 

0-9 

12-8-2 

0-8-2 

11-8-2 

11-8-7 

0-8-5 



A,C 

A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 
A,C 



Commercial at 



\ 



Upper-case letters 



/ 

Opening (left) bracket 
Reverse slant (backslash) 
Closing (right) bracket 
Circumflex 
Underline 
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GRAPHIC 
CHARACTER 



ASCII 
OCTAL 

CODE 



ASCII FORTRAN 

PUNCHED-CARD (A=ANSI) 

CODE (C=CRAY) 



DESCRIPTION 



\ 


140 


8-1 




a 


141 


12-0-1 


C 


b 


142 


12-0-2 


C 


c 


143 


12-0-3 


C 


d 


144 


12-0-4 


C 


e 


145 


12-0-5 


C 


f 


146 


12-0-6 


C 


g 


147 


12-0-7 


C 


h 


150 


12-0-8 


C 


i 


151 


12-0-9 


C 


J 


152 


12-11-1 


C 


k 


153 


12-11-2 


C 


1 


154 


12-11-3 


C 


m 


155 


12-11-4 


C 


n 


156 


12-11-5 


C 


o 


157 


12-11-6 


C 


P 


160 


12-11-7 


C 


q 


161 


12-11-8 


C 


r 


162 


12-11-9 


C 


s 


163 


11-0-2 


C 


t 


164 


11-0-3 


C 


u 


165 


11-0-4 


C 


V 


166 


11-0-5 


C 


w 


167 


11-0-6 


C 


X 


170 


11-0-7 


c 


y 


171 


11-0-8 


C 


z 


172 


11-0-9 


C 


{ 


173 


12-0 




1 

1 


174 


12-11 




} 


175 


11-0 




'V 


176 


11-0-1 





Grave accent (opening single quotation mark) 
\ 



— Lower-case letters 



/ 

Opening (left) brace 

Vertical line 

Closing (right) brace 

Overline (tilde, general accent) 
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I-Ol 



FUNCTION CODES 



The system function codes and permanent dataset function codes are listed 
in the COS EXEC/STP/CSP Internal Reference Manual, publication SM-0040. 
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LOGICAL I/O ROUTINES 



LOGICAL RECORD I/O ROUTINES 

The logical record I/O routines are divided into three basic groups: 
read routines, write routines, and positioning routines. 



READ ROUTINES 

The read routines transfer partial or full records of data from the I/O 
buffer to the user data area. The data is placed in the user data area 
one character per word or in full words depending on the read request 
issued. Figure D-1 provides an overview of the logical read operation. 



$RWDP - Read words, partial mode 

Words are transmitted from the I/O buffer defined by the Dataset 
Parameter Area (DSP) to the area beginning at first word address (FWA) 
until either the word count in A3 is satisfied or an end-of-record is 
encountered. 

Unrecovered data errors do not abort the job; control is returned to the 
caller instead. The caller can use the good data read, (A2) through 
(A4)-l, and then abort. The user can also skip or accept the bad 
data.S If the caller does nothing, the job aborts when the next read 
request occurs. See the Library Reference Manual, CRI publication 
SR-0014, for detailed descriptions of SKIPBAD and ACPTBAD. 

SUBROUTINE NAME: $RWDP 

ENTRY CONDITIONS: (Al) Address of DSP or negative DSP offset 

relative to DSP base (JCDSP) , that is, 
contents of second word of Open Dataset 
Name Table (ODN) 

(A2) FWA of user data area 

(A3) Word count. If count is 0, no data is 
transferred 



§ Deferred implementation 
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I/O BUFFER POINTERS 



DSP 



(A2) -- 




SYSTEM 



Figure D-1. Logical read 
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RETURN CONDITIONS: 



REGISTERS MODIFIED: 



(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Word count 

(A4) Actual LWA+1 (equals FWA if null record) 

(50) Termination mode 

< Read terminated by end-of-record 
= Null record, end-of-file, 

end-of-data, or unrecovered data 
error encountered§ 
> Read terminated by count. If count 
is exhausted simultaneously with 
reaching end-of-record, the 
end-of-record takes precedence . 

(51) Error Status^ 

=0 No errors encountered 

= 1 Unrecovered data error encountered 

(S6) Contains RCW if (SO) <_ and (Sl)=0 

AO, Al, A4, A5, A6 

B.ZA, B.ZB (within B7O3. ..B773) 

SO, SI, S2, S3, S4, S5, S6 

T.ZA (within T708...T778) ,V0, VI 



Example : 



A 


B 


C 


D 


E 


F 


G 


H 


1 


J 


K 


L 


M 


N 





P 


Q 


R 


S 


T 


U 


V 


W 


X 


Y 


Z 


A 


A 


A 


A 


A 


A 


RCW 





1 


2 


3 


k 


5 


6 


7 


8 


9 


A 


A 


A 


A 


A 


A 


RCW 



Data in I/O buffer 



§ Deferred implementation 



(A2) — 



$RWDP 



■f1 



(A3)=2 



A 


B 


C 


D 


E 


F 


G 


H 


1 


J 


K 


L 


M 


N 





P 



User data area 
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$RWDR - Read words, record mode 

This routine resembles $RWDP. However, following the read, the dataset 
is positioned after the end-of-record that terminated the current record. 

Unrecovered data errors cause control to return to the caller. The 
caller can use the good data read, (A2) through (A4)-l, and then abort. 
The user can also skip or accept the bad data.§ If the caller does 
nothing, the job aborts when the next read request occurs. See the 
Library Reference Manual, CRI publication SR-0014, for detailed 
descriptions of SKIPBAD and ACPTBAD. 

SUBROUTINE NAME: SRWDR 

ENTRY CONDITIONS: Same as $RWDP 

RETURN CONDITIONS: Same as 3RWDP 

REGISTERS MODIFIED: Same as $RWDP 



$RCHP - Read characters, partial mode 

The diRCHP routine unpacks characters from the I/O buffer defined by the 
Dataset Parameter Area (DSP) and inserts them into the user data area 
beginning at the first word address (FWA) specified by (A2) until either 
the count is satisfied or an end-of-record is encountered. If an 
end-of-record is encountered first, the remainder of the field specified 
by the character count is filled with blanks. 

Unrecovered data errors cause control to be returned to the caller. The 
caller can use the good data read, (A2) through (A4)-l; and then abort. 
The user can also skip or accept the bad data.§ If the caller does 
nothing, the job aborts when the next read request occurs. See the 
Library Reference Manual, CRI publication SR-0014, for detailed 
descriptions of SKIPBAD and ACPTBAD. 



§ Deferred implementation 
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SUBROUTINE NAME: 
ENTRY CONDITIONS: 



RETURN CONDITIONS 



I 



REGISTERS MODIFIED: 



$RCHP 

(Al) Address of DSP or negative DSP offset 
relative to DSP base (JCDSP) , that is, 
contents of second word of Open Dataset 
Name Table (ODN) 

(A2) FWA of user data area 

(A3) Character count. If count is 0, no data is 
transferred. 

(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Character count 

(A4) Actual LWA+1 (equals FWA if null record) 

(50) Termination mode 

< Read terminated by end-of-record 

= Null record, end-of-file, 

end-of-data, or unrecovered data 
error encountered§ 

> Read terminated by count. If count 
is exhausted simultaneously with 
reaching end-of-record, the 
end-of-record takes precedence 

(51) Error status^ 

=0 No error encountered 

= 1 Unrecovered data error encountered 

(S6) Contains RCW if (SO) £ and (Sl)=0 

AO, Al, A4, A5, A6 

B.ZA, B.ZB (within B708...B778) 

SO, SI, S2, S3, S4, S5, S6 

T.ZA (within T708...T778) 



I § Deferred implementation 
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Example : 



(A2) 



T 


H 


1 


S 


A 


1 


S 


A 




D 


A 


T 


A 


. 


A 


A 


A 


$RCHP 


^ 





















Data in I/O buffer 



(A3)=16 

















T 
















H 
















1 
















S 
















A 
















1 
















S 
















A 
















D 
















A 
















T 














— 


A 




























A 
















A 
















A 



User data area 
$RCHR - Read characters, record mode 

This routine resembles $RCHP. However, following the read, the dataset 
is positioned after the end-of-record that terminates the current record. 

Unrecovered data errors cause control to be returned to the caller. The 
caller can use the good data read, (A2) through (A4)-l, and then abort, 
skip the bad data,^ or accept the bad data.^ If the caller does 
nothing, the job aborts when the next read request occurs. See the 
Library Reference Manual, SR-0014, for detailed descriptions of SKIPBAD 
and ACPTBAD. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 
RETURN CONDITIONS: 
REGISTERS MODIFIED: 



$RCHR 

Same as for $RCHP 
Same as for $RCHP 
Same as for $RCHP 



S Deferred implementation 
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WRITE ROUTINES 

The write routines transfer partial or full records of data from the user 
data area to the I/O buffer. The data is taken from the user data area 
one character per word and packed eight per word or is transferred in 
full words depending on the write operation requested. Figure D-2 
provides an overview of the logical write operation. 



SWWDP - write words, partial mode 

The number of words specified by the count is transmitted from the area 
beginning at first word address (FWA) and is written in the I/O buffer 
defined by the Dataset Parameter Area (DSP) . 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 



RETURN CONDITIONS: 



REGISTERS MODIFIED: 



$WWDP 

(Al) Address of DSP or negative DSP offset 
relative to DSP base ( JCDSP) , that is , 
contents of second word of Open Dataset 
Name Table (ODN) 

(A2) FWA of user data area 

(A3) Word count. If count is 0, no data is 
transferred. 

(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Word count 

(A4) LWA+1 

AO, Al, A4, A5, A6 

B.ZA, B.ZB (within B7O3. ..B778) 

SO, SI, S2, S3, S4, S5, S6 

T.ZA (within TTOg-.-TTTg) 

VO, VI 
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(Al) 



iK-FRST 
•IN 
OUT 
LMT 



I/O BUFFER POINTERS 



DSP 




FIRST 


data 


IN 
OUT 




LIMIT 


data 



/O BUFFER 



F$WDC 





USER 
SYSTEM 



disk 

queue 

manager 



mass 
storage 



Figure D-2 . Logical write 
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Example : 
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D 
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F 


G 
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J 


K 


L 


M 


N 





P 
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S 


T 


U 


V 


W 


X 


Y 


Z 















User data area 



$WWDP 









^ 


— 




-- 


'^ 
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B 
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J 


K 


L 


M 


N 





P 


Q. 


R 


S 


T 


U 


V 


W 


X 


Y 


Z 















I/O buffer 



$ WWDR - Write words, record mode 

The $WWDR routine resembles $WWDP. However, an end-of-re<x>rd RCW 
terminating the record is inserted in the I/O buffer in the next word 
following the data. To write simply an end-of-record, the user issues 
a $WWDR with (A3)=0. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 
RETURN CONDITIONS: 
REGISTERS MODIFIED: 



$WWDR 

Same as $WWDP 
Same as $WWDP 
Same as $WWDP 



$WWDS - Write words, record mode with unused bit count 

The $WWDS routine resembles $WWDR. However, the user may specify the 
unused bit count in the last word of the record as an entry condition. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 



RETURN CONDITIONS: 
REGISTERS MODIFIED: 



$WWDS 

Same as $WWDP with the addition of the 
following: 

(A4) Unused bit count in the last word of the 
record; a value from through 63. 

Same as $WWDP 

Same as $WWDP 
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$WCHP - Write charactersy partial mode 

The $WCHP routine packs the number of characters specified by the 
count from the user area defined at first word address (FWA) to the 
I/O buffer for the dataset defined by the Dataset Parameter Area 
(DSP) . The number of characters specified by the count is packed from 
the area beginning at BWA to the dataset defined by DSP. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 



RETURN CONDITIONS: 



REGISTERS MODIFIED: 



Example: 
(A2)__^ 



(A3)=11 



$WCHP 

(Al) Address of DSP or negative DSP offset 
relative to DSP base ( JCDSP) , that is, 
contents of second word of ODN 

(A2) FWA of user data area 

(A3) Character count. If count is 0, no data 
is transferred. 

(Al) Address of DSP 

(A2) FWA of user data area 

(A3) Character count 

(A4) LWA+1 

AO, Al, A4, A5, A6 

B.ZA, B.ZB (within B703...B778) 

SO, SI, S2, S3, S4, S5, S6 


































u 
















T 
















P 
















u 
















T 
















A 
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A 
















T 
















A 



$WCHP 





1 


previous 1 y 
written data 







U 


T 


P 


U 


T 


A 


D 


A 


T 


A 









I/O buffer 



User data area 



SR-0011 



D-9 



$WCHR - Write characters record mode 

The $WCHR routine resem les $WCHP. However, an end-of-record RCW 
terminating the record is inserted in the I/O buffer in the next full 
word following the data. The unused bit count in the RO«? specifies 
the end of data in the previous word. To write an end-of-record, the 
user issues a $WCHR with (A3)=0. The RCW is written in the next full 
word. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 
RETURN CONDITIONS: 
REGISTERS MODIFIED: 



$WCHR 

Same as $WCHP 
Same as $WCHP 
Same as $WCHP 



$WEOF - Write end of file 

This routine writes an end-of-file RCW preceded by an end-of-record 
RCW if necessary as the next words in the I/O buffer. If the previous 
operation was a call to $WCHP, then a call to $WCHR with (A3) =0 is 
necessary to set the UBC since $WEOF does not check for a partial 
characte" write in progress. 



SUBROUTINE NAME: 



ENTRY CONDITIONS: 



RETURN CONDITIONS: 
REGISTERS MODIFIED; 



$WEOF 

(Al) Address of Dataset Parameter Area (DSP) 
or negative DSP offset relative to DSP 
base (JCDSP) , that is, contents of 
second word of Open Dataset Name Table 
(ODN) 

(Al) Address of DSP 

AO, Al, A2, A3, A4, A5 , A6 

B.ZC (within B708...B778) 

SO, SI, S2, S3, S4, S5, S6 

T.ZB (within T708...T778) 



$WEOD - Write end of data 

This routine writes an end-of-data RCW preceded by an end-of-file and 
an end-of-record if necessary as the next words in the I/O block. If 
the previous operation was a call to $WCHP, then a call to $WCHR with 
(A3)=0 is necessary to set the UBC since $WEOD does not check for a 
partial character write in progress. 
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The $WEOD forces the final block of data to be written on the disk; 
that is, it flushes the I/O buffer. The dataset is left positioned 
before the end-of-data. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 



RETURN CONDITIONS: 
REGISTERS MODIFIED: 



$WEOD 

(Al) Address of Dataset Parameter Area (DSP) 
or negative DSP offset relative to DSP 
base (JCDSP) , that is, contents of 
second word of Open Dataset Name Table 
(ODN) 

(Al) Address of DSP 

AO, Al, A2, A3, A4, A5 , A6 

B.ZD (within B7O3...B773) 

SO, SI, S2, S3, S4, S5, S6 

T.ZB (within T7O3.. .T773) 



POSITIONING ROUTINES 

The positioning routines, except for $GPOS, set the current processing 
direction to input (reading). If the processing direction was 
previously output (writing), on a sequential dataset $WEOD is called 
to write an end-of-data and the buffer is flushed. On a random 
dataset, the buffer is flushed. 



$REWD - Rewind dataset 

The $REWD routine positions the dataset at beginning-of-data. It 
functions as a no-op if the dataset is already positioned there. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 



RETURN CONDITIONS: 
REGISTERS MODIFIED 



$REWD 

(Al) Address of Dataset Parameter Area (DSP) 
or negative DSP offset relative to DSP 
base (JCDSP), that is, contents of 
second word of Open Dataset Parameter 
Area (ODN) 

(Al) Address of DSP 

AO, Al, A2, A3, A4, A5 , A6 

SO, SI, S2, S3, S4, S5, S6 
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$BKSP - Backspace one record 

The $BKSP routine positions the dataset after the previous 
end -of- re cord RCW. If the dataset is positioned just after an 
end-of-record RCW, $BKSP positions it just before the end-of-file RCW, 
that is, $BKSP treats an end-of-file RCW as if it were a normal record 



SUBROUTINE NAME: 



ENTRY CONDITIONS: 



RETURN CONDITIONS: 



REGISTERS MODIFIED 



$BKSP 

(Al) Address of Dataset Parameter Area (DSP) 
or negative DSP offset relative to DSP 
base (JCDSP) , that is, contents of 
second word of Open Dataset Name Table 
(ODN) 

(Al) Address of DSP 

(S6) RCW locationg after which dataset is 
positioned; equals if at 
beginning-of-data 

AO, Al, A2, A3, A4, A5 , A6 

SO, SI, S2, S3, S4, S5, S6 



$BKSPF - Backspace one file 

The $BKSPF routine positions a dataset after the previous end-of-file 
RCW or at beginning-of-data if there is no previous end-of-file. The 
function is a no-op if the dataset is at beginning-of-data. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 
RETURN CONDITIONS: 
REGISTERS MODIFIED; 



$BKSPF 

Same as $BKSP 
Same as $BKSP 
Same as $BKSP 
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$GPOS - Get current dataset position 

The $GPOS routine returns the current dataset position, including the 
current word address and flags that indicate whether the dataset is 
positioned at a record, a file, or a dataset boundary. 

This routine does not alter the dataset position. 

SUBROUTINE NAME: $GPOS 



ENTRY CONDITIONS: 



RETURN CONDITIONS: 



(Al) Address of Dataset Parameter Area (DSP) 
or negative DSP offset relative to DSP 
base (JCDSP) , that is, contents of second 
word of Open Dataset Name Table (ODN) 

(Al) DSP address 

(SI) Dataset position 

Flags - the upper 4 bits of SI indicate 
record, file, and dataset boundaries: 

bits significanc e 

End~of-record flag. 1 indicates 
the dataset is positioned at a 
record boundary, that is, 
following a record control word. 

indicates the dataset is either 
at beginning of data or in the 
middle of a record. 

1 Unused 

2 End-of-file flag. 1 indicates the 
dataset is at a file boundary, 
that is, following the end of file 
RCW. 

3-30 Unused 

31-63 Word address. This is the current 
physical word address within the 
dataset, including record control 
wor ds . 

Note: The entire word in SI is 
at beginning-of-data. 



REGISTERS MODIFIED: AO , Al, A2, A3 

SO, SI, S2, S3, S4 
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$SPOS - Set current dataset position 

The $SPOS routine positions the dataset at the position specified. 
The position must be at a record boundary, that is, at 
beginning-of-data or following an end-of-record or end-of-file, or 
before an end-of-data. A dataset cannot be positioned beyond the 
current end-of-data. 



SUBROUTINE NAME: 
ENTRY CONDITIONS: 



$SPOS 



(Al) 



Address of Dataset Parameter Area (DSP) 
or negative DSP offset relative to DSP 
base (JCDSP) , that is, contents of 
second word of Open Dataset Name Table 
(ODN) 



(SI) Dataset position 

bits significance 
0-30 Unused 

31-63 Word address. The desired 

physical word address within the 
dataset, including record control 
words 



Special cases; 



RETURN CONDITIONS: 



REGISTERS MODIFIED 



(SI) = -1 Denotes end-of-data. The dataset 

is positioned at end-of-data, 
that is, before the end-of-data 
record control word. 

(SI) = Denotes beginning-of-data 

(Al) DSP address 

Dataset position 



(SI) 
(S6) 



Contains RCW after which the dataset is 
positioned; (S6)=0 if at 
beginning-of-data 



AO, Al, A2, A3, A4, A5 , A6 
SO, SI, S2, S3, S4, S5, S6 
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FORTRAN LEVEL I/O 

FORTRAN I/O consists of formatted and unformatted I/O routines, 
buffered I/O routines, and positioning and control I/O routines 

Although they do not perform I/O in the strict sense, the 
encode/ decode routines are also described in this section. 



FORMATTED AND UNFORMATTED I/O ROUTINES 

These routines are divided into six basic groups: read formatted, 
write formatted, read unformatted, write unformatted, encode, and 
decode. 



Routines in the four read and write groups transfer data between user 
locations and the system I/O buffer area allocated to a dataset and 
associated with a particular I/O unit. Routines in the encode and 
decode groups transfer data to or from user locations and a 
user-supplied buffer. The buffer contains eight characters per word 
and has no I/O unit association. All dataset processing by these 
routines is sequential. 

Each of the six groups is accessed through a minimum of two calls: 
the first to an initiation routine and the last to a termination 
routine. Optionally, one or more calls may be made to either of two 
transfer routines between initiation and termination routine calls. 
The initiation routine name is identified by an I uffix, the 
termination routine name by an F suffix. 

Transfer routines are of two types: call by address and call by 
value. Routine names are suffixed by an A if a call-by-address 
routine or by a V if a call-by-value routine. Both types of routines 
can be called within the same sequence. 

These routines are named and their functions summarized in the chart 
below: 



\ OPERATION 

SEQUENCE \ 


READ 
FORMATTED 


WRITE 
FORMATTED 


READ 
UNFORMATTED 


WRITE 
UNFORMATTED 


DECODE 


ENCODE 


INITIATION 
ROUTINES 


$RFI 


$WFI 


$RUI 


$WUI 


$DFI 


$EFI 


TRANSFER 

ROUTINES 

CALL BY'ADDRESS 


$RFA 


$WFA 


$RUA 


$WUA 


$DFA 


$EFA 


TRANSFER 

ROUTINES 

CALL'B? 9ALUE 


$RFV 


$WFV 


$RUV 


$WUV 


$DFV 


$EFV 


TERMINATION 
ROUTINES 


$RFF 


$WFF 


$RUF 


$WUF 


$DFF 


$EFF 
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Type-checking entry points - Each transfer routine has six different 
entry points. Each entry point corresponds to a particular type of data 
to be processed and is specified as the name of the routine (xnam) plus a 
(Parcel) increment value. These entry points and the FORTRAN data types 
they accommodate are: 

Entry Point Type of data 

xnam or Typeless (Boolean) 

xnam + 

xnam + 3 integer 

xnam + 6 Real 

xnam + 9 Double precision 

omam + 12 Complex 

xnam +15 Logical 

The increment entry point names are used by the FORTRAN run- time system 
to verify the correspondence between variable types and format 
speci f ica tions . 

In transfer routines that process formatted data, double-precision values 
must be specified by using the xnam + 9 entry. All other types of values 
may use the appropriately incremented entry or the xnam entry. If the 
xnam entry is used, typing is determined from format specification edit 
descriptors. If the xnam + offset entry is used, the format 
specification must be compatible with the type implied by the entry 
offset. Transfer routines processing unformatted data must be entered at 
xnam + 9 and xnam + 12 for double-precision and complex values. Values 
of all other types may be processed by using the appropriately 
incremented entry or the omam entry. 

Format specifications identified by initiation routines and used by 
transfer routines are described in the CRAY-1 (CFT) FORTRAN Reference 
Manual . 

If an end-of-file record is read, zeros or blanks are supplied in place 
of valid values or characters. An optional end-of-file exit address may 
be supplied to the read-initiation routine to suppress this action. 
Acknowledgement of an end-of-file 's record having been read must occur 
before initiating another read operation at the same unit. This is done 
by: 

• Providing an end-of-file exit address to the read initiation 
routine, 

• Writing, rewinding, or backspacing the dataset, or 

• Calling the utility procedure lEOF. 
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Routine 
Function 

Type of call 
Entry 



Exit 



$DFI 

Decode formatted initialize. Provides 
arguments for subsequent $DFA and $DFV calls. 

By address 

(EP-l) = address of record length in characters 
(EP-2 ) = address of FORMAT specification 
(EP-3) = address of character string 

No arguments returned 



Routine 
Function 

Type of call 
Entry 



Exit 



$DFA (type-checking entry points) 

Decode formatted, call by address. Decodes 
items in a packed character string, placing 
results into an array. 

By address 

($DFA-1) = address of array 

($DFA-2 ) = address of item count 

($DFA-3) = address of item increment 

Items are at user item addresses 



Routine 
Function 

Type of call 

Entry 

Exit 



$DFV (type-checking entry points) 

Decode formatted, call by value. Decodes a 
single item in a character string. 

By value 

No arguments required 

51 contains the decoded item 

52 contains the second word of the decoded 
item, if required 
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Routine 



Function 



Type of call 



$DFF 

Decode formatted final 
sequence . 

No arguments required 



Terminates a decoding 



Routine 
Function 

Type of call 
Entry 



Exit 



$EFI 

Encode formatted initialize. Provides 
arguments for subsequent $EFA and $EFV calls. 

By address 

(EP-1) = address of record length in characters 

(EP-2) = address of FORMAT specification 

(EP-3) = address of character string buffer 

Content of character string buffer 



Routine 
Function 

Type of call 
Entry 



Exit 



$EFA (type-checking entry points) 

Encode formatted, call by address. Encodes 
items in an array, placing results in the 
packed character string buffer. 

By address 

($EFA-1) = address of array 

($EFA-2) = address of item count 

($EFA-3) = address of item increment 

Content of character string buffer 
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Routine 
Function 

Type of call 
Entry 



Exit 



$EFV (type-checking entry points) 

Encode formatted, call by value. Encodes a value 
and places the result in the character string 
buffer . 

By value 

51 contains the value to be encoded 

52 contains the second word of the value to be 
encoded, if required 

Content of character string buffer 



Routine 



Function 



Type of call 



$EFF 



Encode formatted final. Terminates an encoding 
sequence. 



No arguments required 



Routine 
Function 

Type of call 
Entry 



Exit 



$RFI 

Read formatted initialize. Provides arguments 
for subsequent $RFA and $RFV calls 

By address 

(EP~1) = address of unit name or number 

(EP-2) = address of FORMAT specification 

(EP~3) = address of error exit address (optional) 

(EP-4) = address of end-of-file exit address 
(optional) 

(EP-5) = address of status specifier (optional) 

(EP-6) = address of record number for this 

transfer; present if and only if unit is 
connected for direct device 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 
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Routine 



Function 



Type of call 
Entry 



Exit 



Routine 
Function 

Type of call 

Entry 

Exit 



$RFA (type-checking entry points) 

Read formatted, call by address. Decodes and 
moves the number of items specified by (EP-2) to 
locations beginning at (EP-1) as incremented by 
(EP-3) . 

By address 

($RFA-1) = Address of array 

($RFA-2) = address of item count 

($RFA-3) = address of array address increment 

Decoded items are at user item addresses 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 

$RFV (type-checking entry points) 

Read formatted, call by value. Decodes a single 
item. 

By value 

No arguments required 

51 contains the decoded item 

52 contains the second word of the decoded item, 
if required 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 



Routine 
Function 

Type of call 
Exit 



$RFF (type-checking entry points) 

Read formatted final. Terminates a read 
formatted sequence. 

No arguments required 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 
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Routine 
Function 

Type of call 
Entry 



Exit 



$RUI 

Read unformatted initialize. Provides arguments 
for subsequent $RUA and $RUV calls. 

By address 

(EP-1) = address of unit name or number 

(EP-3) = address of error exit address (optional) 

(EP-4) = address of end-of-file exit address 
(optional) 

(EP-5) = address of status specifier (optional) 

(EP-6) = address of record number for this 

transfer; present if and only if unit is 
connected for direct device 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 



Routine 



Function 



Type of call 
Entry 



Exit 



$RUA (type-checking entry points) 

Read unformatted, call by address. Relocates the 
number of words specified by (EP-2) from the I/O 
buffer to locations beginning at (EP-1) as 
incremented by (EP-3) . 

By address 

($RUA-1) = address of array 

($RUA-2) = address of word count 

($RUA-3) = address of array address increment 

Requested words are in the array 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 
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Routine 
Function 

Type of call 

Entry 

Exit 



$RUV (type-checking entry points) 

Read unformatted, call by value. Moves a single 
value from the I/O buffer. 

By value 

No arguments required 

51 contains the r^equested word 

52 contains a second requested word, if required 
(for two-word values) 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 



Routine 
Function 

Type of call 
Exit 



$RUF 



Read unformatted final. Terminates a read 
unformatted sequence. 

No arguments required 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 



Routine 
Function 

Type of call 
Entry 



$WFI 

Write formatted initialize. Provides arguments 
for subsequent $WFA and $WFV calls. 

By address 

(EP-1) = address of unit name or number 

(EP-2) = address of FORMAT specification 

(EP-3) = address of error exit address (optional) 

(EP-4) = address of end-of-file exit address 
(optional) 

(EP-5) = address of status specifier (optional) 

(EP-6) = address of record number for this 

transfer; present if and only if unit is 
connected for direct device 
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Routine 



Function 



Type of call 
Entry 



Exit 



Routine 
Function 

Type of call 
Entry 



Exit 



$WFA (type-checking entry points) 

Write formatted, call by address. Encodes and 

moves to the I/O buffer the number of items 

specified by (EP-2) from locations beginning at 
(EP-1) as incremented by (EP-3) . 

By address 

($WFA-1) = address of array 

($WFA-2) = address of item count 

($WFA-3) = address of array address increment 

Encoded items are in the I/O buffer 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 

$WFV (type-checking entry points) 

Write formatted, call by value. Encodes and 
moves the word(s) provided into the I/O buffer. 

By value 

51 contains the word to be encoded and moved 

52 contains a second word to be encoded and 
moved, if required 

Encoded item is in the I/O buffer 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 



Routine 
Function 

Type of call 
Exit 



$WFF 

Write formatted final. Terminates a write 
formatted sequence. 

No arguments required. 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 
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Routine 
Function 

Type of call 
Entry 



Exit 



$WUI 

Write unformatted initialize. Provides arguments 
for subsequent $WUA and $WUV calls. 

By address 

(EP-1) = address of unit name or number 

(EP-3) = address of error exit address (optional) 

(EP-4) = address of end-of-f ile exit address 
(optional) 

(EP-5) = address of status specifier (optional) 

(EP-6) = address of record number for this 

transfer; present if and only if this 
unit is connected for direct device 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 



Routine 



Function 



Type of call 
Entry 



Exit 



$WUA (type-checking entry points) 

Write unformatted, call by address. Transfers 
the number of words specified by (EP-2) from the 
locations beginning at (EP-1) as incremented by 
(EP-3) . 

By address 

($WUA-1) = address of array 

($WUA-2) = address of word count 

($WUA-3) = address of array increment 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 
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Routine 
Function 

Type of call 
Entry 



Exit 



$WUV (type-checking entry points) 

Write unformatted, call by value. Transfers the 
word(s) provided into the I/O buffer. 

By value 

51 contains the word to be transferred 

52 contains a second word to be transferred, if 
required (for two-word values) 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 



Routine 
Function 

Type of call 
Exit 



$WUF 

Write unformatted final. Terminates a write 
unformatted sequence. 

No arguments returned 

Status specifier provided in initialization call; 
zero if no error, nonzero if error during 
initialization, transfer, or finalization 
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BUFFERED I/O ROUTINES 

Buffered I/O routines perform operations on logical records. Control may 
be returned to the calling program before the I/O transfer is complete. 



Routine 



Function 



Type of call 
Entry 



Exit 



$RB 

Read buffered. Reads (EP-4) - (EP-3) + 1 words 
or until an end-of-record RCW is encountered, 
whichever is first, from the I/O buffer to the 
specified array locations. If (EP-2) < 0, a 
partial record may be read with a subsequent read 
capable of transferring all or part of the 
remaining words in the record. If (EP-2) > 0, a 
subsequent read transfers words from the next 
record. 

By address 

(EP-1) = address of unit name or number 

(EP-2) = address of mode specifier 

(EP-3) = address of first word of array 

(EP-4) = address of last word of array 

No arguments returned 
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Routine 



Function 



Type of call 
Entry 



Exit 



$WB 

Write buffered. Writes (EP-4) + (EP-3) + 1 
words to the I/O buffer from locations (EP-3) 
through (EP-4) of the array. If (EP-2) < 0, a 
partial record may be written with a 
subsequent write capable of transferring all 
or part of the remaining words to the same 
record. If (EP-2) _> 0, a subsequent write 
transfers words to a new record. If (EP-4) is 
set to (EP-3) - 1, the partial record being 
written is terminated. Any attempt to write 
past the end of the allocated area or after 
encountering an end-of-data results in job 
abortion. 

By address 

(EP-1) = address of unit name or number 

(EP-2) = address of mode specifier 

(EP-3) = address of first word of array 

(EP-4) = address of last word of array 

No arguments returned 



POSITIONING AND CONTROL I/O ROUTINES 

The FORTRAN I/O routines descibed below perform dataset positioning 
and control operations: 



Routine 
Function 

Type of call 

Entry 

Exit 



$EOFW 

Write end-of-file. This function writes an 
end-of-file record on the specified dataset, 

By address 

(EP-1) = address of unit name or number 

No arguments returned 
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Routine 
Function 

Type of call 

Entry 

Exit 



$BACK 

Backspace record. Positions the dataset to 
the start of the preceding record. 

By address 

(EP-1) = address of unit name or number 

No arguments returned 



Routine 
Function 

Type of call 

Entry 

Exit 



$REWF 

Rewind function. Rewinds the specified 
dataset to the beginning-of-data point. 

By address 

(EP-1) = address of unit name or number 

No arguments returned 



Routine 



Function 



Type of call 



$TRBK 

Abort function. Makes the $FTLIB error 
procedure available to user programs. Returns 
to the error entrance to COS, not to the 
calling program. 

No arguments required 
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EXCHANGE PACKAGE 



O 2 



iO 12 14 16 18 




n-i-8 
n-f9 



n+K) 



n-MI 



n+12 



n + 13 
n + 14 



s 

R'RAB 

P 
BA 
LA 
XA 



Registers 

Syndrome bits 

Read address for error 
(where B is bank) 

Program address 

Base address 

Limit address 

Exchange address 



M - Modes 



VL Vector length 

E - Error type (bits Qsl of n ) 
10 Uncorrectable memory 
01 Correctable memory 

R - Read mode (bits 10,11 of n) 

00 Scalar 

01 I/O 

10 Vector 

11 Fetch 



n+1 


39 


Interrupt monitor mode*^ 


n+2 


36 


Interrupt on correctable 
memory error 


n+2 


37 


Interrupt on floating point 
error 


n+2 


38 


Interrupt on uncorrectable 
memory error 


n+2 


39 


Monitor mode 
F - Flags 


n+3 


31 


Programmable clock interrupt 


n+3 


32 


MCU interrupt 


n+3 


33 


Floating point error 


n+3 


34 


Operand range error 


n+3 


35 


Program range error 


n+3 


36 


Memory error 


n+3 


37 


I/O interrupt 


n+3 


38 


Error exit 


n+3 


39 


Normal exit 



ft 



t Supports Monitor Mode Interrupt option on CRAY-IA and CRAY-IB. 

It Supports Programmable Clock (optional on CRAY-IA and CRAY-IB; standard 
on CRAY-1 S Series computers) 
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ERROR AND STATUS CODES 



SYSTEM ERROR CODES 

Table F-1 describes the system error codes as released. Installation 
differences can change data in this table. Consult the on-site 
analyst for details. The CRAY-OS Message Manual, publication SR-0039, 
also contains additional descripions of the abort codes and their 
corresponding messages. 



Table F-1. Error codes for reprieve processing 







Reprieve Error 




System 


Fatal/ 


Class (Octal 




Error Code 


Non-fatal 


Mask Value) 


Description 


ABO 01 


NF 


4 


End-of-file on read 


ABO 02 


NF 


4 


Invalid LOCK or UNLOCK indicator 


ABO 03 


F 


4 


Device Allocation Table exhausted 


AB004 


NF 


4 


Dataset not open 


ABO 05 


NF 


4 


Invalid dataset open request 


ABO 06 


NF 


4 


No read permission 


ABO 07 


NF 


4 


No write permission 


ABO 08 


NF 


4 


Illegal bit set in RFL request word 


ABO 09 


NF 


4 


Attempt to delete memory outside 
program area 


ABOIO 


F 


400 


No available disk space 


ABO 11 


F 


4000 


System directory is full 


AB012 


NF 


4 


Job Table Area overflow 


ABO 13 


NF 


4 


More memory requested than 
available 


AB014 


NF 


4 


More memory requested than allowed 


ABO 15 


NF 


2000 


Unknown acquire error 


AB016 


NF 


2000 


Subdataset $IN cannot be disposed 



SR-0011 



F-1 



1-02 



Table F-1. Error codes for reprieve processing (continued) 







Reprieve Error 




System 


Fatal/ 


Class (Octal 




Error Code 


Non-fatal 


Mask Value) 


Description 


AB017 


NF 


4 


Invalid dataset close request 


AB018 


NF 


4 


Dataset already opened 


AB019 


NOT RI 


2PRIEVABLE 


Job Communication Block destroyed 


ABO 20 


NF 


4 


Invalid system request parameter 


ABO 21 


NF 


4 


Dataset not found 


AB022 


NF 


4 


Invalid program load dataset 


ABO 23 


F 


200 


Job time limit exceeded 


ABO 24 


F 


10 


Operator dropped user job 


AB025 


NF 


2 


User program requested abort 


ABO 2 6 


NF 


4 


Invalid (undefined) user request 


ABO 27 


NF 


4 


Call not between user BA and LA 


ABO 28^ 


NF 




XP errors (no message) 


ABO 2 9 


NF 


4 


Logical device name not found 


ABO 30 


NF 


4 


Block number error 


ABO 31 


NF 


4 


Unrecoverable data error 


ABO 32 


NF 


4 


Unrecoverable hardware error 


AB033 


NF 


4 


Read after write or after EOD 


ABO 34 


NF 


4 


Unknown error 


ABO 3 5 


NF 


4 


Invalid processing direction 


ABO 36 


NF 


4 


Dataset prematurely terminated 


ABO 3 7 


NF 


4 


Dataset Parameter Table invalid 


ABO 3 8 


NOT RE 


PRIEVABLE 


Operator killed user job 


ABO 3 9 


NF 


20 


Operator reran the job 


AB040 


NF 


4 


Invalid disposition code 


ABO 41 


F 


4000 


"Enter" allowed on access only 



§ The ABO 28 error code is set during abort processing when any Exchange 
Package error flag is set. It does not represent a single reprievable 
condition. One of the Exchange Package error codes (AB053 through 
AB058) will be set later to indicate the appropriate error. 
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Table F-1. Error codes for reprieve processing (continued) 







Reprieve Error 




System 


Fatal/ 


Class (Octal 




Error Code 


Non-fatal 


Mask Value) 


Description 


AB043 


F 


400 


Allowable user log size exceeded 


ABO 4 4 


NF 


4 


Invalid dataset name 


ABO 4 5 


NF 


400 


Specified LM is too big 


ABO 4 6 


NF 


400 


Dataset size limit exceeded 


ABO 4 7 


NF 


2000 


Dataset not available from station 


ABO 4 8 


NF 


2000 


Dataset cannot be saved on a front 
end 


ABO 4 9 


NF 


4 


Invalid LFTs in user area 
« 


ABO 51 


F 


4 


Invalid pointer to first JTA LFT 


AB052 


NF 


4 


No user LFT DN matches JTA LFT 


ABO 5 3 


NF 


100 


Floating-point error 


ABO 5 4 


NF 


4 


Operand range error 


AB055 


NF 


4 


Program range error 


ABO 5 6 


NF 


40 


Uncorrected memory error 


AB057 


NOT REPRIEVABLE 


Interactive ABORT 


ABO 58 


F 


4 


Error exit 


ABO 61 


NF 


4 


No invoke request provided 


AB062 


NF 


4 


Invoke request abort pending 


ABO 6 3 


NF 


4 


Invoke length not multiple of 512 


ABO 6 4 


NF 


4 


Invoke length greater than maximum 


AB066 


NF 


4 


Dataset has related disposes active 


ABO 6 7 


NF 


4 


Invalid procedure dataset 


AB068 


NF 


4 


Procedure nest level exceeded 


AB070 


NF 


10000 


An ATTENTION request command was 
entered at an interactive terminal. 


ABO 71 


NF 


4 


Bad class structure 


ABO 7 2 


NF 


4 


DSP destroyed by user 


ABO 7 3 


NF 


4 


Undefined function code in F$INS 

1 ' 
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Table F-1. Error codes for reprieve processing (continued] 







Reprieve Error 






System 


Fatal/ 


Class (Octal 






Error Code 


Non-fatal 


Mask Value) 


Description 




ABO 7 4 


NF 


4000 


DUMPJOB processing has been 
inhibited 




ABO 7 5 


NF 


4000 


No permissions granted while 
dataset is execute-only 




ABO 7 6 


NF 


4 


Dataset is already accessed by 
job 


the 


ABO 7 7 


NOT Ri 


:prievable 


CSP internal error 




ABO 7 8 


NF 


4000 


Privileged system request 




ABO 7 9 


NF 


4 


Unassigned JCL symbol 




ABO 80 


NF 


4 


Receive buffer too small 




ABO 81 


NF 


4 


Undefined JCL symbol 




ABO 82 


NF 


4 


JCL symbol cannot be modified 




ABO 8 3 


NF 


4 


Invalid message class 





PERMANENT DATASET STATUS CODES 

The permanent dataset status octal codes are flagged in the PMST field of 
the Permanent Dataset Definition Table (PDD) which is presented in 

Appendix A. 

PMST Status 

I Complete; no error 

II A DNT cannot be found for the specified dataset, 
21 Maintenance permission not granted 

31 Edition already exists 

41 DSC full 

51 Function code out of range 
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PMST Status 

61 The job has a dataset of the local name (DN) specified. 

71 No permission granted 

101 Delay and try again 

111 DSC does not contain the requested dataset. 

121 Edition does not exist 

131 PDS full 

141 Dataset not permanent 

151 PDS entry not found 

161 Continuation error 

171 DAT full 

201 DNT full 

211 End of DSC 

221 PDN already accessed by this job 

231 Request to read zero pages 

241 Invalid page number requested 

251 No data has been written to disk 

261 SDT does not exist 

271 SDT not on input or output queue 

301 Unable to queue SDT 

311 Dataset name in PDD is 

331 Multiple editions of the dataset exist, prohibiting changes 
to the permission control words. 

3 41 Unique access is not acceptable because the dataset is part 
of the System Directory. 

3 51 The PDD contains a text length without a text address, or a 
text address without a length specified. 

3 61 The text length specified exceeds the allowable maximum. 

371 The device on which all or part of the dataset resides is down 

4 21 Access is denied because crossed allocation unit exists. 

441 The DSC entry was flagged by Startup as containing a fatal 
error. Access is denied. 
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PMST Status 

461 No available QDT entries exist to coordinate the dispose. 

471 The dataset has outstanding disposes; do not deallocate disk 
space. 

501 Allocation of multitype dataset inconsistent with related 
datasets 

511 Multitype dataset has non-existent QDT entry. 

521 Maximum edition reached 
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GLOSSARY 



Abort - To terminate a program or job when a condition (hardware or 
software) exists from which the program or computer cannot recover. 

Absolute address - (1) An address that is permanently assigned by the 
machine designator to a storage location. (2) A pattern of characters 
that identifies a unique storage location without further modification. 
Synonymous with machine address. 

Absolute block - Loader tables consisting of the image of a program in 
memory. It can be saved on a dataset for subsequent reloading and 
execution. 

Address - (1) An identification, as represented by a name, label, or 
number, for a register, location in storage, or any other data source or 
destination such as the location of a station in a communication 
network. (2) Any part of an instruction that specifies the location of 
an operand for the instruction. 

Allocate - To reserve an amount of some resource in a computing system 
for a specific purpose (usually refers to a data storage medium) . 

Alphabetic - A character set including, $, %, @, as well as the 26 
uppercase letters A through Z. 

Alphanumeric - A character set including all alphabetic characters and 
the digits through 9. 

Arithmetic operator - Part of an expression that indicates action to be 
performed during evaluation of expression; can be symbolic character 
representing addition, unary plus, subtraction, unary minus, 
multiplication, or division. 

Assemble - To prepare an object language program from a symbolic language 
program by substituting machine operation codes for symbolic operation 
codes and absolute or relocatable addresses for symbolic instructions. 



B 

Base address - The starting absolute address of the memory field length 
assigned to the user's job. This address is maintained in the base 
address (BA) register. The base address must be a multiple of 20g. 
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$BLD - A dataset on which load modules are placed by a compiler or 
assembler unless the user designates some other dataset. 

Blank common block - A common block into which data cannot be stored at 
load time. The first declaration need not be the largest. The blank 
common block is allocated after all other blocks have been processed. 

Block - (1) A tape block is a collection of characters written or read as 
a unit. Blocks are separated by an interblock gap and may be from 1 
through 1,048,576 bytes. A tape block and a physical record are 
synonymous on magnetic tape. (2) In CRAY-l blocked format, a block is a 
fixed number of contiguous characters preceded by a block control word as 
the first word of the block. The internal block size for the CRAY-l is 
512 words (one sector on disk) . In CRAY-l manuals, the terms tape block 
and 512-word block are consistently used to distinguish between the two 
uses. 

Block control word - A word occurring at the beginning of each block in 
the CRAY-l blocked format that identifies the sequential position of the 
block in the dataset and points forward to the next block control word. 

BOT - Beginning of tape; the position of the beg inning-of- tape reflective 
marker. 

BOV - Beginning of volume. See BOT. 

BPI - Bits per inch. COS supports the 1600 and 6250 bpi recording 
densities. 

Buffer - A storage device used to compensate for the difference in rate 
of flow of data, or time of occurrence of events, when transmitting data 
from one device to another. It is normally a block of memory used by the 
system to transmit data from one place to another. Buffers are usually 
associated with the I/O system. 

Buffer Memory - A 64-bit memory in the I/O Subsystem common to all I/O 
Processors. 



C 

Call - The transfer of control to a specified closed routine. 

Card image - A one-to-one representation of the contents of a punched 
card, for example, a matrix in which a 1 represents a punch and a 
represents the absence of a punch. In CRAY-l blocked format, each card 
image is a record. 



SR-0011 Glossary-2 J-01 



Catalog (noun) - A list or table of items with descriptive data, usually 
arranged so that a specific kind of information can be readily located. 

Channel - A path along which signals can be sent. 

Character - A logical unit composed of bits representing alphabetic, 
numeric, and special symbols. The CRAY-l software processes 8-bit 
characters in the ASCII character set. 

Code - (1) A system of character and rules representing information in a 
form understandable by a computer. (2) Translation of a problem into a 
computer language. 

Common block - A block that can be declared by more than one program 
module during a load operation. More than one program module can specify 
data for a common block but if a conflict occurs, information from later 
programs is loaded over previously loaded information. A program may 
declare no common blocks or as many as 125 common blocks. The two types 
of common blocks are labeled and blank. 

Conditional control statement block - Defines the conditions under which 
a group of control statements are to be processed. The statements which 
define the block and conditions are: IF, ELSE, ELSEIF, and ENDIF. 

Control statement - The format, consisting of a verb and its parameters, 
used to control the operating system and access its products. Directives 
are used to control products. 

Control statement input file - A dataset containing valid control 
statements as its first file. 

$CS - A primary control statement input file. 



Data - (1) Information manipulated by or produced by a computer program. 
(2) Empirical numerical values and numerical constants used in arithmetic 
calculation. Data is considered to be that which is transformed by a 
process to produce the evidence of work. Parameters, device input, and 
working storage are considered data. 



SR-0011 Glossary-3 J-01 



Dataset - A quantity of information maintained on mass storage by the 
CRAY-1 Operating System. Each dataset is identified by a symbolic name 
called a dataset name. Datasets are of two types: temporary and 
permanent. A temporary dataset is available only to the job that created 
it. A permanent dataset is available to the system and to other jobs and 
is maintained across system deadstarts. 

Dataset name verb - A verb that is the name of a dataset. See local or 
system dataset name verb. 

Deadstart - The process by which an inactive machine is brought up to an 
operational condition ready to process jobs. 

Debug - To detect, locate, and remove mistakes from a routine or 
malfunction of a computer. Synonymous with troubleshoot. 

Delimiter - A character that separates items in a control statement or a 
directive; synonymous with separator. 

Density - See tape density. 

Device - A piece of equipment that mechanically contains and drives a 
recording medium. 

Directive - A command used to control a product, such as UPDATE. 

Diagnostic - (1) Pertaining to the detection and isolation of a 
malfunction or a mistake. (2) A message printed when an assembler or 
compiler detects a program error. 

Disposition code - A code used in I/O processing to indicate the 
disposition to be made of a dataset when its corresponding job is 
terminated or the dataset is released. 

Dump - (1) To copy the contents of all or part of a storage device, 
usually from internal storage, at a given instant of time. (2) The 
process of performing (1). (3) The document resulting from (1). 
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End-of-data delimiter - Indicates the end of a dataset. In CRAY-1 
blocked format, this is a record control word with a 17 g in the mode 
field. 

End-of-file delimiter - Indicates the end of a file. (1) In CRAY-1 
blocked format, this is a record control word with a 16g in the mode 
field. (2) On magnetic tape, this is a tapemark. 

End-of-record delimiter - Indicates the end of a record. (1) In CRAY-l 
blocked format, this is a record control word with a 10 3 in the mode 
field. (2) In an ASCII punched deck, this is indicated by the end of 
each card. 

Entry point - A location within a block that can be referenced from 
program blocks that do not declare the block. Each entry point has a 
unique name associated with it. The loader is given a list of entry 
points in a loader table. A block can contain any number of entry points. 

An entry point name must be 1 to 8 characters and cannot contain the 
characters blank, asterisk, or slash. Some language processors (i.e., 
FORTRAN) may produce entry point names under more restricted formats due 
to their own requirements. 

EOD - End-of-data on tape. The definition of EOD is a function of 
whether the tape is labeled or nonlabeled and of the type of operation 
being performed (input or output). When reading a labeled tape, EOD is 
returned to the user when an EOPl trailer label is encountered. When 
reading a nonlabeled tape, EOD is returned when a tapemark is read on the 
last volume in the volume list for a particular dataset. When writing a 
labeled or nonlabeled tape, EOD processing is initiated by a write EOD, 
rewind, close, or release request. 

EOI - End-of- information; see EOD. 

EOT - End-of-tape; a status, set only on a write operation indicating 
sensing of the end of the tape reflective marker. 

EOV - End-of-volume. On output, EOV occurs when end-of-tape status is 
returned on a write operation. This status occurs when the EOT 
reflective marker is sensed by the tape device. For input of a labeled 
tape dataset, EOV occurs when an EOVl trailer label is read; for input of 
a nonlabeled dataset, EOV is returned when a tapemark is encountered and 
the volume list is not exhausted. 

Exchange package - A 16-word block of data in memory which is associated 
with a particular computer program or memory field. It contains the 
basic parameters necessary to provide continuity from one execution 
interval for the program to the next. 
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Expression (JCL parameter expression) - A series of characters grouped 
into operands and operators which are computed as one value during 
parameter evaluation; should be delimited by parentheses. 

External reference - A reference in one program block to an entry point 
in a block not declared by that program. Throughout the loading process, 
externals are matched to entry points (this is also referred to as 
satisfying externals) ; that is, addresses referencing externals are 
supplied with the correct address. 



File - A collection of records in a dataset. In CRAY-1 blocked format, a 
file is terminated by a record control word with 16 g in the mode field. 

Filemark - Refer to tapemark. 

Foreign label - A special condition that can occur during the label scan 
at the beginning of a tape. If a NOT CAPABLE status is returned on a BOV 
label scan, TQM declares the tape to be foreign labeled (FRN) which 
protects a 7-track tape or a 9-track, 800 bpi tape from being accidently 
destroyed. 

Formal parameter specifications - Parameters in a procedure definition 
which identify the character strings within the procedure body that can 
be substituted during the procedure's evaluation. 

Front-end processor - A computer connected to a CRAY-l channel. The 
front-end processor supplies data and jobs to the CRAY-l and processes or 
distributes the output from the jobs. Front end systems are also 
referred to as stations in Cray publications. 



Generic name - Tape resource requirements are expressed using generic 
names or installation-defined synonyms. A generic name corresponds to a 
device type. COS supports up to 16 generic names^. A generic name may 
be represented by a synonym. 

H 
I HLM - High-level memory, the user's program and data area in memory. 



§ Deferred implementation 
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$IN - A dataset containing the job control language statements as well as 
the source input and data for compilers and assemblers, unless the user 
designates some other dataset (FT05 for example) . 

In-line procedure - A procedure defined in a control statement file. 

Input/Output - (1) Commonly called I/O. To communicate from external 
equipment to the computer and vice versa. (2) The data involved in such 
a communication. (3) Equipment used to communicate with a computer. (4) 
The media carrying the data for input/output. 

Integer constant - Specifies an octal value or a decimal value that can 
be signed as positive or negative. 

Interchange format - One of the two ways in which tape datasets can be 
read or written. Each tape block of data corresponds to a single logical 
record in COS blocked format. Interchange format is selected by setting 
DF=IC when a tape dataset is accessed. As far as I/O routines in the 
CRAY-1 mainframe are concerned, interchange datasets must be in CRAY 
blocked format because the CRAY blocked structure (BCW's and RCW*s) is 
used to describe each tape block read or written. This blocked structure 
allows the user to write or read variable- length tape blocks at high 
speed with data resolution to the 88-bit byte level of the tape device. 
The record control word (RCW) is used to define the tape block length on 
output and to describe the block length on input. No BCW or RCW ever 
appears in the data written on the tape. 

Interblock gaps - The physical separation between successive tape blocks 
on magnetic tape. 

I/O Subsystem - Part of a CRAY-1 S Series Model S/1200 through S/4400 
consisting of two to four I/O processors and one-half, one, four, or 
eight million words of shared Buffer Memory. The optional tape subsystem 
is composed of at least one block multiplexer channel, one tape 
controller, and two tape units. The tape units supported are 
IBM-compatible 9-track, 200 ips, 1600/6250 bpi devices. 

Iterative control statement block - Defines the repeated execution of a 
series of statements if a condition is satisfied 
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JCL block control statement - A statement in the control statement file 
that is part of a group of control statements called a block which 
specifies an action to be taken by COS; the three types of blocks are: 
procedure defintion, conditional, and iterative. 

Job - (1) An arbitrarily defined parcel of work submitted to a computing 
system, (2) A collection of tasks submitted to the system and treated by 
the system as an entity. A job is presented to the system as a formatted 
dataset. With respect to a job, the system is parametrically controlled 
by the content of the job dataset. 

Job Communication Block - The first 200g words of the job memory 
field. This area is used to hold the current control statement and 
certain job-related parameters. The area is accessible to the user, the 
operating system, and the loader for inter-phase job communication. 

Job control statement - Any of the statements used to direct the 
operating system in its functioning, as compared to data, programs, or 
other information needed to process a job but not intended directly for 
the operating system, itself. A control statement may be expressed in 
card, card image, or user terminal keyboard entry medium. 

Job deck - The physical representation of a job before processing either 
as a deck of cards or as a group of records. The first file of the job 
dataset contains the job statements and the job parameters which will be 
used to control the job. Following files contain the program and data 
which the job will require for the various job control statements. The 
job deck is terminated by an end-of-data delimiter. 

Job input dataset - A dataset named $IN on which the card images of the 
job deck are maintained. This consists of programs and data referenced 
by various job steps. The user can manipulate the dataset like any othr 
dataset (excluding write operations) . 

Job output dataset - Any of a set of datasets recognized by the system by 
a special dataset name (e.g., $OUT, $PIiOT, and $PUNCH) , which becomes a 
system permanent dataset at job end and is automatically staged to a 
front- end computer for processing. 

Job step - A unit of work within a job, such as source language 
compilation or object program execution. 



K 

Keyword parameter - A string of 1 to 8 alphanumeric characters that 
consists of a keyword followed by one or more values; identified by its 
form rather than by its position in the control statement. 
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L 
I $LOG - See logfile. 

Labeled common - A common block into which data can be stored at load 
time. 

Library - A dataset composed of sequentially organized records and 
files. The last file of the library contains a library directory. The 
rest of the files and records, known as entries, can consist of processed 
procedure definitions and/or relocatable modules. The directory gives a 
listing of entry names with their associated characteristics. 

Library-defined verb - A one through eight character name of a program or 
procedure definition residing in a library that is a part of the current 
library searchlist. 

Limit address - The upper address of a memory field. This address is 
maintained in the limit address (LA) register. 

Literal - A symbol which names, describes, or defines itself and not 
something else that it might represent. 

Literal constant - A string of one through eight characters delimited 
with apostrophes whose ordinal numbers are in the range 040 g through 
176g; value of a character constant corresponds to the ASCII character 
codes positioned within a 64-bit word; alignment indicated can be left or 
right adjusted and zero-filled or left-adjusted and space-filled; 
apostrophes remain as part of value. 

Literal string - A string delimited with apostrophes which are normally 
not treated as part of the value, except with JCL block control 
statements which treat the apostrophes as part of the string value. 

Loader tables - The form in which code is presented to the loader. Loader 
tables are generated by compilers and assemblers according to loader 
requirements. The tables contain information required for loading such 
as type of code, names, types and lengths of storage blocks, data to be 
stored, etc. 

Loading - The placement of instructions and data into memory so that it 
is ready for execution. Loader input is obtained from one or more 
datasets and/or libraries. Upon completion of loading, execution of the 
program in the job's memory field is optionally initiated. Loading may 
also involve the performance of load-related services such as generation 
9f a loader map, presetting of unused memory to a user- specified value, 
and generation of overlays. 

Load point - See BOT. 

Local dataset - A temporary or permanent dataset accessible by the user. 
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Local dataset name verb - A verb that is the name of a local dataset 
consisting of an alphabetic character followed by one through six 
alphanumeric characters. Requests that COS load and execute an absolute 
binary program from the first record of the named dataset. 

Loqf ile - During the processing of the job, a special dataset named $LOG 
is maintained. At job termination, this dataset is appended to the $OUT 
file for the job. The job logfile serves as a time-ordered record of the 
activities of the job — all control statements processed by the job, 
significant information such as dataset usage, all operator interactions 
with a job, and errors detected during processing of the job. 

Logical operator - Represents logical function performed on operands on a 
bit-by-bit basis, returning a 64-bit result; functions are: inclusive OR, 
intersection, exclusive OR, unary complement. 



M 

Macro instruction - An instruction in a source language that is 
equivalent to a specified sequence of machine instructions. 

Magnetic tape - A tape with a magnetic surface on which data can be 
stored by selective polarization of portions of that surface. 

Mainframe - The central processor of the computer system. It contains 
the arithmetic unit and special register groups. It does not include 
input, output, or peripheral units and usually does not include internal 
storage. Synonymous with central processing unit (CPU) . 

Mass storage - The storage of a large amount of data that is also readily 
accessible to the central processing unit of a computer. 

Memory field - A portion of memory containing instructions and data 
usually defined for a specific job. Field limits are defined by the base 
address and the limit address. A program in the memory field cannot 
execute outside of the field nor refer to operands outside of the field. 

Multiprocessing - Utilization of several computers to logically or 
functionally divide jobs or processors, and to execute various programs 
or segments asynchronously and simultaneously. 
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Multiprogramming - A technique for handling multiple routines or programs 
simultaneously by overlapping or interleaving their execution, that is, 
permitting more than one program to time-share machine components. 

N 

Nesting - Including a block of statements of one kind into a larger 
block of statements of the same kind, such as an iterative block within a 
larger iterative block. 

Not Capable - A tape status indicating the reel currently mounted cannot 
be read by the control unit and drive. The Not Capable status would be 
returned if an 800 bpi tape were mounted on a device that supported only 
1600 and 6250 bpi, for example. Since it is not possible to read a Not 
Capable tape to verify label type and contents, COS rejects (unloads) all 
tapes that return a Not Capable status. 



$OUT - A dataset that contains the list output from compilers and 
assemblers unless the user designates some other dataset. At job end, 
the job logfile is added to the $OUT dataset and the dataset is sent to a 
front-end computer. 

Operand - A character string in an expression that is operated on during 
evaluation; types are integer constant, literal constant, symbolic 
variable, and subexpresion. 

Operating system - (1) The executive, monitor, utility, and any other 
routines necessary for the performance of a computer system. (2) A 
resident executive program that automates certain aspects of machine 
operation, particularly as they relate to initiating and controlling the 
processing of jobs. 

Operator - A symbolic representation indicating the action to be 
performed in an expression; types are arithmetic, relational, and logical 
operators. 

Overlaying - A technique for bringing routines into memory from some 
other form of storage during processing so that several routines will 
occupy the same storage locations at different times. Overlaying is used 
when the total memory requirements for instructions exceeds the available 
memory . 
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$PROC - A dataset to which in-line procedure definitions are written. 

Parameter - A quantity in a control statement which may be given 
different values when the control statement is used for a specific 
purpose or process. 

Parcel - A 16-bit portion of a word which is addressable for instruction 
execution but not for operand references. An instruction occupies one or 
two parcels; if it occupies two parcels, they may be in separate words. 

Parenthetic string - A string delimited with parentheses instead of 
apostrophes; parentheses are treated as part of the string when evaluted 
except when preceded by an initial, parameter, equivalence, or 
concatenation separator character. 

Permanent dataset - A dataset known to the operating system as being 
permanent; the dataset survives deadstart. 

Positional parameter - A parameter that must appear in a precise position 
relative to the separators in the control statement. 

Procedure - A named sequence of control statements and/or data that is 
saved in a library for processing at a later time when activated by a 
call to its name by a calling statement; provides the capability of 
replacing values within the procedure with other values. 

Procedure defintion - The definition of a procedure that is saved in a 
library to be called for processing at a later time; if defined in a job 
control statement is called an in-line procedure definition. 

Program - (1) A sequence of coded instructions that solves a problem, 
(2) To plan the procedures for solving a problem. This may involve 
analyzing the problem, preparing a flow diagram, providing details, 
developing and testing subroutines, allocating storage, specifying I/O 
formats, and incorporating a computer run into a complete data processing 
system. 

Program block - The block within a load module usually containing 
executable code. It is automatically declared for each program (though 
it may be zero^length) . It is local to the module; that is, it can be 
accessed from other load modules only through use of external symbols. 
Data placed in a program block always comes from its own load module. 

Program name - Also referred to as IDENT name or deck name, the name 
contained in the loader PDT table at the beginning of each load module. 
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Program library - (PL) The base dataset used hy the UPDATE utility. This 
dataset consists of one or more specially formatted card image decks, 
each separated by an end-of-file. 



R 

Record - A group of contiguous words or characters related to each other 
by virtue of convention. A record may be fixed or variable length. (1) 
In CRAY-1 blocked format, a record ends with a record control word with 
lOg in the mode field. (2) In an ASCII coded punched deck, each card 
is a record. (3) For a listable dataset, each line is a rcord. (4) For 
a binary load dataset, each module is a record. 

Relational operator - An oprator that indicates the comparison to be 
performed between the operands in an expression (-1 for a TRUE result and 
for a FALSE result) ; types are equal, not equal, less than, greater 
than, less than or equal, and greater than or equal. 

Relative address - An address defined by its relationship to a base 
address (e.g., the (BA) ) such that the base address has a relative 
address of 0, 

Relocatable address - An address presented to the loader in such a form 
that it can be loaded anywhere in the memory field. A relocatable 
address is defined as being relative to the beginning address of a load 
module program block or common block. 

Relocatable module - This is the basic program unit produced by a 
compiler or assembler. CAL produces a relocatable module from source 
statements delineated by IDENT and END. In FORTRAN, the corresponding 
beginning statements are PROGRAM, SUBROUTINE, BLOCK DATA, or FUNCTION. 
The corresponding end statement is END. 

A relocatable module consists of several loader tables that define 
blocks, their contents, and address relocation information. 

Relocate - In programming, to move a routine from one portion of internal 
storage to another and to adjust the necessary address references so that 
the routine can be executed in its new location. Instruction addresses 
are modified relative to a fixed point or origin. If the instruction is 
modified using an address below the reference point, relocation is 
negative. If addresses are above the reference point, relocation is 
positive. Generally, a program is loaded using positive relocation. 
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Sector - A physical area on disk equivalent to 512 CRAY-1 words. In 
CRAY-l blocked format, a block is also 512 contiguous words with a block 
control word as the first word of the block. Therefore the internal 
block size for the CRAY-l is equivalent to one CRAY-1 disk sector. This 
is the unit of data transfer between the CRAY-1 mainframe and the 1/0 
Subsystem. 

Separator - Synonym for delimiter. 

String - A sequence of characters delimited by apostrophes or parentheses 
which is to be taken literally as a parameter value; see literal string 
and parenthetic string. 

Subexpression - An expression that is evaluated so that its result 
becomes an operand. 

Substitution parameters - Parameters on procedure definition prototype 
statement or procedure calling statement which provide replacement values 
to be substituted during evaluation for strings flagged within the 
procedure body. 

Symbolic variable - A string of one to eight alphanumeric characters, * 
beginning with an alpha character that represents values maintained by 
COS and/or the user. 

System dataset name verb - A verb that is the name of a system-defined 
dataset in the System Directory Table (SDR) ; consists of an alphabetic 
character which can be followed by one through six alphanumeric 
characters. 

I System logfile - A permanent dataset named $SYSTEMLOG. 

System verb - Requests that COS perform a function; consists of an 
alphabetic character which can be followed by one through six 
alphanumeric characters 



Table - A collection of data, each item being uniquely identified either 
by some label or by its relative position. 

Tape block - A group of contiguous characters recorded on and read from 
magnetic tape as a unit. 
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Tape control unit - A piece of equipment connected to a block multiplexer 
channel that provides the capability for controlling the operation of one 
or more tape devices. Up to four control units may be combined to drive 
a maximum of 16 tape devices. The control units are cross connected to 
all devices. Such a configuration is called a 4x16 (four by sixteen) . 
If one control unit were to be connected to three devices, it would be 
referred to as a 1x3 configuration. 

Tape density (bpi) - The number of bits per inch on magnetic tape. COS 
supports 6250 bpi and 1600 bpi. 

Tape format - The way tape datasets are read or written. In 
interchange format, each tape block of data corresponds to a single 
logical record in COS blocked format. In transparent format, each tape 
block is a fixed multiple of 512 words based on the density of the tape. 

Tape volume - A reel of magnetic tape. 

Tapemark - A special hardware bit configuration recorded on magnetic 
tape. It indicates the boundary between combinations of datasets and 
labels. It is sometimes called a filemark. 

TDT - Tape Device Table entry. Contains one entry for each device in the 
configuration. A TDT entry is used to control the activity associated 
with a tape device and contains the six-word packet through which 
requests to the I/O Subsystem are made. 

Temporary dataset - A dataset which is not permanent and is available 
only to the job that created it. 

Time slice - The maximum amount of time during which the CPU can be 
assigned to a job without re-evaluation as to which job should have the 
CPU next. 

Transparent format - One of two ways tape datasets are read or written. 
Each tape block is a fixed multiple of 512 words. Transparent format is 
the default tape dataset format and is designated by setting DF=TR when 
accessing a tape dataset. This format produces a fixed-length block 
dataset (16384 bytes at 1600 bpi or 32768 bytes at 6250 bpi) that may be 
a CRAY blocked or unblocked dataset as far as any I/O routines are 
concerned. The tape subsytem merely takes four (1600 bpi) or eight (6250 
bpi) sectors and processes them as one physical tape block. When a short 
block is read, it is considered to be EOD. 
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u 

Unit record device - A device such as a card reader, printer, or card 
punch for which each unit of data to be processed is considered a record. 

Unload - To remove a tape from ready status by rewinding beyond the load 
point. The tape is then no longer under control of the computer. 

Unsatisfied external - An external reference for which the loader has not 
yet loaded a module containing the matching entry point. 

User logfile - A dataset named $LCX3 created for a job when it is 
initiated by the Job Scheduler. 



V 

Verb - The first nonblank field of a control statement; specifies the 
action to be taken by COS during control statement evaluation. 

Volume - A dismountable physical unit of storage media, for example, a 
reel of magnetic tape. 

Volume identifier - Up to six alphanumeric characters used to identify a 
physical reel of tape. On labeled tapes, the volume identifier is 
actually recorded on tape in the volume header label. Volume identifier 
is synonomous with volume serial number. 

VSN - Volume serial number. See volume identifier. 



W 

Word - A group of bits between boundaries imposed by the computer. Word 
size must be considered in the implementation of logical divisions such 
as character. The word size of the CRAY-1 is 64-bits. 
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ABORT macro, (3)2-6 
ACCESS control statement, (2)4-4 
ACCESS macro, (3)4-9 
ACCOUNT control statement, (2)1-10 
ACQUIRE control statement, (2)5-1 
Address relocation, (2)9-16 
ADJUST control statement, (2)4-9 
ADJUST macro, (3)4-10 
Alphabetic characters, (1)4-3 
Alphanumeric characters, (1)4-3 
Analytical aids, (2)8-1 
Apostrophes 

in block control statements, (1)4-13 
in procedure definitions, (2)2-7 
ARGADD macro, (3)5-6 
ASCII character set, B-1 
ASSIGN control statement, (2)3-1 
Asynchronous READ/WRITE, (3)3-8 
AUDIT control statement, (2)7-6 



Begin Code Execution Table, A-18 

BGN (see Begin Code Execution Table) 

BKSP macro, (3)3-16 

BKSPF macro, (3)3-17 

Blank common, (2)10-4,10-13 

Blank compression, (1)2-10 

Block control statements 

parentheses, (1)4-11 
Block control word (BCW) , (1)2-6 
Blocked datasets 

blank compression, (1)2-6 

block control word, (1)2-4.1 

record control word, (1)2-5 
Blocked format, (1)2-5 
BREG macro, (3)5-5 
BUFCHECK macro, (3)3-13 
BUFEOD macro, (3)3-12 
BUFEOF macro, (3)3-11 
BUFIN macro, (3)3-9 
BUFINP macro, (3)3-9 
BUFOUT macro, (3)3-10 
BUFOUTP macro, (3)3-10 
BUILD statement, (2)11-3 
BUILD directives 

COPY directive, (2)11-7 

FROM directive, (2)11-6 

LIST directive, (2)11-9 

OMIT directive, (2)11-7 

examples, (2)11-9 
Bulletin, system, (1)3-8 



CALL control statement, (2)1-9 
CALL macro, (3)5-1 



CALLV macro, (3)5-2 

$CCS, (1)4-11 

Central memory assignment and 

characteristics, (1)1-2 
Central Processing Unit, (1)1-1 
CFT linkage macros, (3)5-1 
Character set, B-1 
CHARGES control statement, (2)1-11 
CLOSE macro, (3)2-17 

Comment (*) control statement, (2)1-6.1 
COMPARE control statement, (2)8-11 
Compression, blank, (1)2-10 
Conditional control statements, (2)2-1,13 

block with ELSE and ELSEIF, (2)2-19 

conditional block, (2)2-13 

ELSE control statement, (2)2-16 

ELSEIF control statement, (2)2-18 

ENDIF control statement, (2)2-14 

IF control statement, (2)2-14 

job advancement, (1)3-4 

table entries, A-21 
Constants 

ingeger, (1)4-7 

literal, (1)4-7 
Control statements 

blanks, (1)4-1 

comments, (1)4-1 

continuation, (1)4-1 

dataset name verbs, (1)4-2, 3 

echo macro, (3)2-4 

file, (1)3-1,4-1 

library-defined verbs, (1)4-3 

literal delimiter, (1)4-5 

parameter, (1)4-4 

separator, (1)4-4 

syntax, (1)4-1 

syntax violations, (1)4-2 

system verbs, (1)4-2 

verb, (1)4-2 

verb search order, (1)4-3 
Control word 

block, (1)2-6 

record, (1)2-7 
CONTRPV macro, (3)2-9 
COPYD control statement, (2)6-3 
COPYF control statement, (2)6-2 
COPYR control statement, (2)6-1 
COS (see Operating System) 
CPU (see Central Processing Unit) 
Cracking, parameters, (1)4-11 
CRAY-l configuration, (1)1-1 
Cross-reference listing, (2)8-16 
$CS , (1)3-3, 4, 4-1 
CSECHO control macro, (3)2-4 
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$DUMP, (2)8-1 

&DATA control statement, (2)2-4 

Dataset 

accessing, (2)4-3,5-1 

changing size of, (2)3-2 

control, (2)3-1 

control statement, (1)4-1 

creation and definition, (2)3-1 

disposition codes, (1)2-15, (2)5-5 

editions, (2)4-1,4-7 

execute-only, (1)2-3 

formats, (1)2-5 

interactive, (1)2-4 

maintenance control words, (2)4-2 

memory resident, (1)2-4 

name verb, (1)4-2 

naming conventions, (1)2-5 

size, (2)3-2 

staging, (2)5-1 

types, (1)2-1 

user identification, (2)4-4,4-6 

utilities, (2)6-1 
Dataset Catalog, (2)4-1 
Dataset Definition List, A-19 
Dataset management macros, (3)2-13 
Dataset name verb, (1)4-2 
Dataset Parameter Area, (3)2-13,A-7 
Datasets 

blocked, (1)2-4 

interactive, (1)2-4,2-7 

local, (1)1-6,2-1 

magnetic tape, (1)2-2 

memory resident, (1)2-4 

permanent, (1)1-6,2-1 

temporary, (1)2-1 

unblocked, (1)2-7 
DATE macro, (3)2-19 
Date as symbol, (1)4-9 
DDL (see Dataset Definition List) 
DEBUG control statement, (2)8-6 
Debugging macros, (3)2-21 
Default value in procedure definition, 

(2)2-7 
DELAY macro, (3)2-6 
DELETE control statement, (2)4-11 
DELETE macro, (3)4-10 
Disk storage units, (1)1-6,1-7 
DISPOSE control statement, (2)5-4 
DISPOSE macro, (3)2-18 
Disposition codes, dataset, (1)2-15 
DSC (see Dataset Catalog) 
DSDUMP control statement, (2)8-8 
DSP (see Dataset Parameter Area) 
DSP macro, (3)2-13 
DUMP control statement, (2)8-2 
DUMP macro, (3)2-22 
DUMPJOB control statement, (2)8-1 
DUMPJOB macro, (3)2-13 



ECHO control statement, (2)1-13 
ELSE control statement, (2)2-16 
ELSEIF control statement, (2)2-18 
ENDIF control statement, (2)2-14 



ENDLOOP control statement, (2)2-22 

ENDP macro, (3)2-10 

ENDPROC control statement, (2)2-5 

ENDRPV macro, (3)2-10 

ENTER macro, (3)5-2 

Error codes, F-1 

Execute-only datasets, (1)2-3 

Exchange package, E-1 

EXIT control statement, (2)1-5 

EXIT control statement macro, (3)5-4 

EXITLOOP control statement, (2)2-22 

Expression 

definition and kinds, (1)4-7 

evaluation, (1)4-11 

operator table, (1)4-10 

write value on logfile, (2)8-13 



Field length, (2)1-5 

FLODUMP control statement, (2)8-14 

Flow trace tables, (2)8-14 

Format 

blocked, (1)2-5 

interactive, (1)2-10 

interchange, (1)2-11 

transparent, (1)2-13 

unblocked, (1)2-10 
Formats 

dataset, (1)2-5 

tape I/O, (1)2-11 
FORTRAN I/O, (1)2-7,D-15 
FORTRAN I/O routines 

buffered, D-24.2 

formatted, D-15 

positioning, D-25 

unformatted, D-15 
FREAD macro, (3)2-32 
Front-end computer, (1)1-1 
Function codes, C-1 
FWRITE macro, (3)2-33 



GETMODE macro, (3)2-39 
GETPARAM routine, (1)4-11 
GETPOS macro, (3)3-18 
GETSWS macro, (3)2-40 



Hardware requirements, (1)1-1 



IF control statement, (2)2-14 

$IN , (1)3-3, 4 

In-line procedure, (2)2-1 

INPUT macro, (3)2-24 

INSFUN macro, (3)2-40 

Integer constants, (1)4-7 

Interactive 

capabilities, (1)1-1 

datasets, (1)2-4 

format, (1)2-10 
Interchange format, (1)2-11 
Interfaces, user logical I/O, (1)2-13 
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I/O, (1)2-7 

lOAREA control statement, (2)1-8 

lOAREA macro, (3)2-12 

Iterative control statements, (2)2-1,21 
ENDLOOP control statement, (2)2-22 
EXITLOOP control statement, (2)2-22 
LOOP control statement, (2)2-21 
table entries, A-21 



JBI (see JCL Block Information Table) 
JCB (see Job Communication Block) 
JCL Block Information Table, A-23 
JCL parameter expressions, (1)4-7 
JCL Symbol .Table, A-24 
JDATE macro, (3)2-20 
Job 

accounting information, (1)3-8 

class, (2)1-4 

definition to system, (1)2-2 

field length as variable, (1)4-9 

flow, (1)3-2 

identification, (2)1-3 

logfile, (1)3-7 

memory field length, (2)1-3 

name, (2)1-3 

priority, (2)1-4 

processing requirements, (2)1-3 

protect for recovery, (2)1-12 

rerunnability, (2)1-7 

resource accounting, (2)1-11 

time as symbol, (1)4-9 

time limit, (2)1-3 

user area, A-1 

user field, (1)1-4, A-1 

user number, (2)1-4 
Job Communication Block, (l)l-5,A-2 
JOB control statement, (2)1-3(2)2-2 
Job control statements, (1)4-1,(2)1-1 
Job control language (see Control statements) 
Job control macros, (3)2-1 
Job deck dataset, (1)3-1 
Job deck structure, (1)3-1 
Job definition, (2)1-3 
Job flow 

advancement, (1)3-3 
abort, (1)3-3 
normal, (1)3-3 

entry, (1)3-2 

initiation, (1)3-2 

reprieve processing, (1)3-6,(3)2-7 

rerun, (1)3-5 

termination, (1)3-4 
Job identification, (2)1-3 
Job processing, (1)3-2 
Job step abort, (1)4-1,(2)2-3 
Job step accounting, (2)1-10 
Job Table Area, (1)1-5, A-2 
JST (see JCL Symbol Table) 
JTA (see Job Table Area) 
JTIME macro, (3)2-5 



Keyed default value in procedure definition, 

(2)2-7 
Keyword parameters, (1)4-6 

in procedure definition, (2)2-6 



Label Definition Table, A-25 
LDR control statement, (2)9-1 
LDT (see Label Definition Table) 
LDT macro, (3)4-7 
LFT (see Logical File Table) 
Library datasets, (2)11-1 
Library-defined verb, (1)4-2, 3 
Library searchlist, (1)4-3 

change, (2)1-14 
LIBRARY control statement, (2)1-14 
Literal constants, (1)4-7 
Literal string, (1)4-11 
Loader 

map control, (2)9-9 

errors, (2)9-7 
Loader, Overlay (see Overlay Loader) 
Loader, Relocatable (see Relocatable Loader) 
Load map 

block list, (2)9-9 

description, (2)9-9 

entry list, (2)9-11 

example, (2)9-10 
LOADREGS macro, (3)2-38 
Local dataset name, (1)2-4 
Local dataset name verb, (1)4-2, 3 
Local datasets, (1)2-1 
$LOG, (1)3-3, 4 
Logfile 

description, (1)3-6 

example, (1)3-7 

print JCL messages, (2)1-13 
Logical File Table, A-6 
Logical I/O, (1)2-7,D-1 
Logical I/O macros, (3)3-1 

asynchronous read/write, (3)3-8 

positioning, (3)3-16 

synchronous read/write, (3)3-1 

unblocked read/write, (3)3-13 
Logical I/O routines, (1)2-7,D-1 
Logical operators, (1)4-11 
Logical Record I/O 

positioning routines, D-11 

read routines, D-1 

write routines, D-6.1 
LOOP control statement, (2)2-21 



Macro instructions, (3)1-1 
Magnetic tape 

characteristics, (1)1-8 

datasets, (1)2-2 
Maintenance Control Unit, (1)1-1 
Management, permanent dataset, (3)4-9 
Mass storage 

subsystem, (1)1-1, 1-5 

characteristics, (1)1-5 

permanent datasets, (1)2-2 
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MCU. (see Maintenance Control Unit) 
Memory 

assignment, (1)1-2 

field length, (2)1-5 

operating system resident, (1)1-4 

size, (1)1-1 

user area, (1)1-4, A-1 
Memory-resident COS, (1)1-4 
Memory resident datasets, (1)2-4 
MEMORY macro, (3)2-2 
MESSAGE macro, (3)2-3 
MODE control statement, (2)1-5 
MODE macro, (3)2-4.1 
MODIFY control statement, (2)4-9 



Named common, (2)10-4,10-13 
Naming conventions, dataset, (1)2-5 
NORERUN control statement, (2)1-6 
NORERUN macro, (3)2-11 



ODN (see Open Dataset Name Table) 

Open Dataset Name Table, A-21 

Operands, (1)4-7 

Operating mode, (2)1-4 

Operating system 
description, (1)1-1 
job processing, (1)3-2 
memory assignment to, (1)1-3 
memory resident COS, (1)1-3 

Operators, expression, (1)4-8 
arithmetic, (1)4-8 
relational, (1)4-8 
logical, (1)4-11 

OPEN macro, (3)2-15 
examples, (3)2-16 

OPTION control statement, (2)1-15 

OPTION Table, A-22 

OPT (see OPTION Table) 

$OUT, (1)3-3, 4 

OUTPUT macro, (3)2-27 

Overlay calls 

FORTRAN, (2)10-9,10-16 

CAL language, (2)10-10,10-17 

Overlay directives 

FILE directive, (2)10-2 
OVLDN directive, (2)10-2 
OVLL directive, (2)10-13 
POVL directive, (2)10-6 
ROOT directive, (2)10-4 
SBCA directive, (2)10-3 
SOVL directive, (2)10-6 

Overlay generation 

directives, (2)10-2,10-13 
examples, (2)10-7,10-15 
log, (2)10-11,10-18 
rules, (2)10-7,10-14 

Overlays 

execution of, (2)10-8 
levels, (2)10-3 
Type 1, (2)10-3 
Type 2, (2)10-11 



Parameters 

definition, (1)4-4 

interpretation of, (1)4-11 

keyword, (1)4-6 

positional, (1)4-4 
Parentheses 

in block control statements, (1)4-13 

in procedure definitions, (2)2-7 
PDD (see Permanent Dataset Definition Table) 
PDD macro, (3)4-1 
PDSDUMP control statement, (2)7-1 
PDSLOAD control statement, (2)7-4 
Permanent Dataset 



(3)4-1, A-13 
(2)4-1,7-1 



Definition Table, 
Permanent datasets 

control statements, 

definition, (3)4-1 

macros, (3)4-1 

management , (3)4-9 

mass storage, (1)2-2 

system, (1)2-2 

user, (1)2-1 

utilities, (2)7-1 
POSITION macro, (3)3-20 
Positional parameters, (1)4-4 

in procedure definition, (2)2-6 
PRINT control statement, (2)8-13 
$PROC, (2)1-14 

PROC control statement, (2)2-3 
Procedure definition, (2)2-1 

apostrophes and parentheses, (2)2-7 

&DATA control statement, (2)2-4 

ENDPROC control statement, (2)2-5 

examples, (2)2-8 

format, (2)2-2 

PROC control statement, (2)2-3 

Procedure definition body, (2)2-4 

Prototype control statement, (2)2-3 

Substitution parameters, (2)2-5 
Procedure calling statement, (2)1-9 
Program module groups, (2)11-1 
Program modules, (2)11-1 
Program module names, (2)11-1 
Program module ranges, (2)11-2 
Prototype statement, (2)2-3 



READ macro, (3)3-1 

Read routines, D-1 

READC macro, (3)3-4 

READCP macro, (3)3-4 

READP macro, (3)3-1 

READU macro, (3)3-14 

RECALL macro, (3)2-5 

Record control word, (1)2-7 

RELEASE control statement, (2)3-4 

RELEASE macro, (3)2-17 

Relocatable loader 

features of, (2)9-1 

LDR control statement, (2)9-1 

load map, (2)9-7 

map control, (2)9-4 

selective load, (2)9-10 
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Relocatable overlays 

address relocation, (2)9-16 

description, (2)9-13 

generation, (2)9-13 

existing, memory layout, (2)9-14 

image, memory layout, (2)9-15 
Relocation, address, (2)9-16 
Reprieve processing, (1)3-6 

classes, (3)2-9 

error codes, F-1 

mask values, (3)2-9 
RERUN control statement, (2)1-7 
RERUN macro, (3) 2-11 
Resource accounting, (2)1-10 
RETURN control statement, (2)1-9 
REWIND control statement, (2)6-5 
REWIND macro, (3)3-16 
RFL control statement, (2)1-6 
ROLL macro, (3)2-10 
ROLLJOB control statement, (2)1-12 



SAVE control statement, (2)4-2 

SAVE macro, (3)4-9 

SAVEREGS macro, (3)2-37 

SDR (see System Directory Table) 

Selective load, (2)9-11 

Selective load directives 

EXCLUDE directive, (2)9-12 

INCLUDE directive, (2)9-12 
Sense switch as symbol, (1)4-9 
Separators, (1)4-4,5 
SET control statement, (2)1-12 
SETPOS macro, (3)3-19 
SETRPV macro, (3)2-7 
SKIPD control statement, (2)6-5 
SKIPF control statement, (2)6-4 
SKIPR control statement, (2)6-3 
SNAP macro, (3)2-21 
Startup, system, (1)1-1,1-2 
Status codes, F-4 
Strings, (1)4-11 

continuation, (1)4-12 

length, (1)4-12 

literal, (1)4-11 

null, (1)4-12 

parenthetic, (1)4-11 
Subexpression, (1)4-8 
SUBMIT control statement, (2)5-9 
SUBMIT macro, (3)2-18 
Substitution parameters, (2)2-1 
SWITCH control statement, (2)1-6 
SWITCH macro, (3)2-4.1 
Symbolic dump, (2)8-6 
Symbolic variable, (1)4-8 

change value, (2)1-12 

table of, (1)4-9 
SYSTD macro, (3)2-39 
SYSREF control statement, (2)8-16 
System action request macros, (3)2-1 
System bulletin, (1)3-8 
System dataset name verb, (1)4-2, 3 
System Directory Table, (1)4-3 



System error codes, F-1 
in expression, (1)4-9 
System initialization, (1)1-2 
System level as symbol, (1)4-9 
System permanent datasets, (1)2-2 
System startup, (1)1-1 
System verb, (1)4-2 



Tape I/O formats, (1)2-11 
Temporary datasets, (1)2-1 
Terminator, (1)4-5 
TIME macro, (3)2-19 
Time as symbol, (1)4-9 
Transparent format, (1)2-13 
TREG macro, (3)5-5 



UFREAD macro, (3)2-35 
UFWRITE macro, (3)2-36 
Unblocked 

datasets, (1)2-7 

format, (1)2-10 

READ/WRITE, (3)3-13 
User account number, (2)1-10 
User area of memory, (1)1-3 
User field, (1)1-5, A-1 
User logical I/O interface, (1)2-13 
User permanent datasets, (1)2-1 



Verb 

control statement, (1)4-2 
search order, (1)4-3 
types of, (1)4-2, 3 



WRITE macro, (3)3-5 

Write routines, D-6.1 

WRITEC macro, (3)3-6 

WRITECP macro, (3)3-6 

WRITED macro, (3)3-8 

WRITEDS control statement, (2)6-6 

WRITEP macro, (3)3-7 

WRITE? macro, (3) 3-5 

WRITEU macro, (3)3-15 



SR~0011 



Index- 5 



J-01 



COS 

CONTROL STATEMENT 

AND 

MACRO SUMMARY 



COS CONTROL STATEMENT 
AND MACRO SUMMARY 



This section summarizes all of the control statements in the COS job 
control language and the macros included with COS. 



Control statement section 

A parameter shown in all UPPERCASE letters must be coded literally as 
shown, while a value must be substituted for an italicized item. For 
certain parameters, all possible values that can be taken are listed in 
braces; in these cases, the default value, if one exists, is underlined. 

In the left margin is a reference to the location of additional 
information on each control statement. In most cases, this reference is 
to a page number in Part 2 of this manual. However, for those control 
statements that are documented in other Cray Research publications, the 
reference is to the corresponding publication number. 



Macro instruction section 

Detailed descriptions of each macro instruction provided with COS are 
given in part 3 of this manual. Included here is a list of these macros 
with references to their locations in part 3. 
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CONTROL STATEMENTS 

pq./pub. Control statement 

1-7 * aomnent text 

2-4 SDATAfdn. 

4-4 ACCESS , xsS'dn , PDN=pin , iD=uid , ED=ed , Rsrd , w=«t , Krmn , UQ , le , na , cs=«a , df^/ , xf!=dt , FSEC^eec , is=lb , MBS^nie , new , 

XDT=i/j/ddd,RT=r't,VOL=uoli iVoV^ : . . .votn,Cl=at,'BS-rf,'BS=v8. 

1-10 ACCOUNT,AC=ac,PW=pW. 

5-1 ACQUIRE,DN=dn,PDN=^dn,ID=Mii,ED=e(i,RT=r't,R=r'<i,W=Wt,M=mn,UQ,TEXT=texi:,MF=m/,TID=t-td,DF=d/. 

4-9 ADJUST, DN-dn,NA. 

SN-0036 APML,l«^<JM,L=Zdn,B=Mn,E«edn, ABORT, DEBUG,op*ion8,LlST=name,S=edn,SYM=e!/m,T=b8t,Xs=a;dn. 

3-1 ASSIGN,DN-<in,S»8i3e,BS=blfc,DV=Jdu,DT=dt,DF=d/,RDM,U,MR,m=Zm,DC=de,BFI=b/i,A=Mn. 

7-6 AUDIT, L«i(in,B=bdn,PDN=pdn,lD=Mi<i,PREFlX=p/x,DV=<iD7i,SZ=(i83,X=OTn/(i<i/i/j((i 'hh:nm:ee' tTCR^mm/dd/yyt 'hh:mm:eB' , 
TLA=fflm/(ii/j/!/j • hh:mm: as' ,TlH=mi/dd/yy: ' hh:mn: ee' . 

11-3 BUILD, l=idn,L=ldn,OBL=odn,B=Mn,NBL=ndn,SORT,NODlR,REPLACE . 

SR-0000 CAL, l-ic&i, L« Jdn, B=Mn,E«e(in, ABORT, DEBUG, options, LlST=name,S=8dM,s™=8j/m,T=fc8t,X=«d?i. 

1-8 CALL,DN«>(in,CNS. 

SR-0009 CFT,l»i£&i,L=Jdn,B=M?i,CPC(in,E=n,ON=8t:r'i?ig',OFF=8tr^?ig',TRUNC=n«,AlDS=aid8,OPT=optioM. 

1-11 CHARGES, SR-optione, 

8-11 COMPARE, A=a<in,B«bdn,L"ld!n,DF-(i/,ME=maa:e,CP=epn,CS»(J8n,CW«(3i(?i [ :cW2 J ,ABORT=acj. 

6-3 OOPYD,l=iin,0=odn. 

6-2 COPYF,l=£dM,0"0<in,NF=n. 

6-1 COPyR,I»i(in,0=odn,NR=n. 

SH-0050 CSIM,L»Zcin,I=idn,LINES=n,T=tJ,MAXBK=m8,VMEM=ym. 

8-6 DEBUG, I=^in,0=vdn,DUMP==din,TRACE'm,SXMS=82/m,NOTSYMS==ne!/m,MAXDIM===dim,BIXX;KS-fclfc,NOTBI^S=nilk,PA(^^ 

4-11 DELETE, DN'<!n,NA. 

6-4 DISPOSE, DN"<in,SDN-8dn,DC=^C,DF==d/,MF==m/,SP=8/',ID=Mi£i,TID=t:id,ED=ed,RT=l»t,R==r'd,W«%Jt,M=mn,TEXT=te«<:, 
WAIT, NOWAIT, DEFER, NRLS. 

8-8 DSDUMP, l=idn,0«=o(iM,DF=(if , iw=M,NW=n, IR»w,NR=n, lF=n,NF=n, lS=n,NS=n . 

8-2 DUMP , i''idn,o=odn, FW=/!Ja, LW=iwa, jta, NXP ,v , dsp , format=/, center. 

8-1 DUMPJOB. 

1-13 ECaO, Oli=olassi:alass 2- • • • :clae8^,0FF=ciassi:class2! • •• :claee^. 

2-16 ELSE. 

2-18 ELSEIF (earpress-ion) 

2-14 ENDIF. 

2-22 ENDLOOP. 

2-5 ENDPROC. 

1-5 exit. 

2-22 exitloop. or EXITLOOP (earpreeeion) 

8-14 FLODUMP. 

2-14 IF (expr»es8-iow) 

1-8 IOAREA I, I-OCK 1 
I UNLOCK I 

1-3 JOB,JN=jn,M=fZ,T=tl,P=p,US=M8,OLM=oim,CL=jc;n,*g'M=nr'. 

9-1 LDR,DN=dn,LIB=WM,NOLlB=ldn,LLD,AB=adn,MAP=op,SlD='etr'ing",T=tm,NX,DEB=l,C,OVL=di7»,CNS,NA,USA,L=Icin,SET=t;al,E=n,l=e(iir'. 
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pq./pub. Control statement 

1-14 hlBRMiY ,DN=dn-^:dn 2 dn^n,V. 

2-21 LOOP. 

1-5 MODE,M=OTode. 

MODIFY, DN=dn,PDN=pdn,ID=Mid,ED=ed,RT=r'<;,R=r'd,W=yt,W=Wt:,M=mn,NA,EXO=j ON 1 , 

I OFF) 



4-9 



1-7 NORERUN ,™^'^^ 

\ DISABLE 

1-15 OPTION,LPP=n,STAT=|ON 1 

I OFF] ' 

7-1 PDSDUMP,DN=?dn,DV=Wv,PDS=pds,CW=C!U,ID=Kid,US=weM,ED=ed,X,C,D,I,0,S. 

7-4 PDSL0AD,DN=(in,PDS=pd8,CW=aW,ID=wid,US=M8n,ED=ed,DV=dun,A,I,0,S,NA. 

8-13 PRINT (expr»eeeionj 

2-3 PROC. 

3-4 RELEASE,DN=dni:dn2!'" tdnQiHOLD.^ 

1-7 RERUN i,^*'*^^^ 1. 

\ disable) 

1-9 return, abort. 

6-5 REWIND, DN^nj^:<in2 driQ. 

1-6 RFL,M=/l. 

1-12 ROLLJOB. 

4-12 SAVE,DN=dn,PDN=pdn,ID=wi(i,ED=ed,RT=r't,R=r'd,W=wt,M=mn,UQ,NA,EXO=|°N I . 

(OFF) 

1-12 SE1 {eymbot=expve8sion) 

6-5 SKIPD,DN^«. 

6-4 SKIPF,DN=cfn,NF=n. 

6-3 SKIPR,DN=iin,NR=n. 

SR-0033 SKOL,l==£dn,L=idn,X=ia;dM,E=edn,0=odn,M=wd«,VIEW,LISTOFF. 

5-9 SUBMIT, DN=cin,SID=m/,DID=m/,TID=tid, DEFER, NRLS. 
1-6 SWITCH, n=X. 

8-16 SYSREF,X=a;<in,L=Wn. 

P 

SR-0013 UPDATE, P=pldri,i=i(in,C=cpZdM,N=npZdn,L=Wn,E=edn,S=edM,*=m,/=c;,DW=iiu,DC=de, [, Q=dki:dk2: • - -dk^j ] , [options] . 

6-6 WRITEDS,DN=(in,NR=nr',RL=r'i. 



§ Deferred implementation 
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